DrakariaDEV

Authentication

Learn how to authenticate with the Drakaria API

Authentication

The Drakaria API supports two authentication methods: Email-based authentication with verification codes and WebAuthn/Passkey authentication for enhanced security.

Authentication Methods

1. Email Authentication (Recommended for Getting Started)

Email authentication uses 6-digit verification codes sent to your email address. This is the simplest way to get started with the Drakaria API.

2. WebAuthn/Passkey Authentication (Most Secure)

WebAuthn allows you to use biometric authentication (Face ID, Touch ID, Windows Hello) or hardware security keys (YubiKey) for a more secure and convenient login experience.

Session-Based Authentication

Once authenticated, you receive a session ID that remains valid for 5 years. Include this session ID in all subsequent API requests.

Using Session Tokens

Include your session token in the Authorization header:

curl https://api.drakaria.com/api/v1/account \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Alternatively, you can use a cookie:

curl https://api.drakaria.com/api/v1/account \
  -H "Cookie: acc-session=YOUR_SESSION_TOKEN"

Email Authentication Flow

Step 1: Sign Up (New Users)

Create a new account by providing an email and display name:

POST /api/v1/auth/signup
Content-Type: application/json

{
  "email": "user@example.com",
  "displayName": "DragonSlayer42"
}

Response: A 6-digit verification code is sent to your email.

Notes:

  • Display names must be unique (case-insensitive)
  • Verification codes expire in 10 minutes

Step 1 Alternative: Login (Existing Users)

If you already have an account, request a login code:

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com"
}

Response: A 6-digit verification code is sent to your email.

Step 2: Verify Your Code

Submit the verification code received via email:

POST /api/v1/auth/confirm
Content-Type: application/json

{
  "code": 123456
}

Response:

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "660e8400-e29b-41d4-a716-446655440001"
}

Save the sessionId - this is your authentication token for all future requests!

WebAuthn/Passkey Authentication

WebAuthn provides a more secure alternative to passwords using biometric authentication or hardware security keys.

Registering a Passkey (Requires Existing Session)

You must already be authenticated to register a passkey.

Step 1: Begin Registration

POST /api/v1/webauthn/register/begin
Authorization: Bearer YOUR_SESSION_TOKEN

Response:

{
  "publicKey": {
    "challenge": "base64-string",
    "rp": {
      "name": "Drakaria",
      "id": "drakaria.com"
    },
    "user": {
      "id": "base64-user-id",
      "name": "user@example.com",
      "displayName": "DragonSlayer42"
    }
    // ... additional WebAuthn options
  }
}

Step 2: Create Credential (Client-Side)

Use the browser's WebAuthn API to create a credential:

const publicKey = response.publicKey; // From step 1
const credential = await navigator.credentials.create({ publicKey });

Step 3: Finish Registration

Submit the created credential:

POST /api/v1/webauthn/register/finish
Authorization: Bearer YOUR_SESSION_TOKEN
Content-Type: application/json

{
  // WebAuthn CredentialCreationResponse
}

Step 4: Set Credential Metadata (Optional)

Give your passkey a friendly name:

POST /api/v1/webauthn/register/creds/metadata
Authorization: Bearer YOUR_SESSION_TOKEN
Content-Type: application/json

{
  "credId": "credential-id-string",
  "deviceName": "My iPhone 15",
  "userAgent": "Mozilla/5.0...",
  "platform": "iOS",
  "createdAt": "2025-11-21T10:30:00Z"
}

Logging In with a Passkey

Step 1: Begin Authentication

POST /api/v1/webauthn/login/begin
Content-Type: application/json

{
  "email": "user@example.com"
}

Response:

{
  "publicKey": {
    "challenge": "base64-string",
    "timeout": 60000,
    "rpId": "drakaria.com",
    "allowCredentials": [
      {
        "type": "public-key",
        "id": "base64-credential-id"
      }
    ]
  }
}

Step 2: Get Credential (Client-Side)

const publicKey = response.publicKey; // From step 1
const assertion = await navigator.credentials.get({ publicKey });

Step 3: Finish Authentication

POST /api/v1/webauthn/login/finish
Content-Type: application/json

{
  "email": "user@example.com",
  // ... WebAuthn assertion response
}

Response:

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "660e8400-e29b-41d4-a716-446655440001"
}

Managing Passkeys

Delete a Passkey

Remove a registered passkey from your account:

DELETE /api/v1/webauthn/cred/{credId}
Authorization: Bearer YOUR_SESSION_TOKEN

Check Display Name Availability

Before signing up, check if a display name is available:

POST /api/v1/auth/check-displayname
Content-Type: application/json

{
  "displayName": "DragonSlayer42"
}

Response:

{
  "validDisplayName": true
}

Best Practices

Security

  • Keep session tokens secure: Never expose session tokens in client-side code or public repositories
  • Use HTTPS only: All API requests must be made over HTTPS
  • Enable WebAuthn: For maximum security, register a passkey after your initial email authentication
  • Store tokens securely: Use secure storage mechanisms (e.g., HTTPOnly cookies, secure keychains)

Session Management

  • Session duration: Sessions are valid for 5 years from creation
  • Multiple sessions: You can have multiple active sessions across different devices
  • Session storage: Sessions are cached in Redis for fast authentication checks

Error Handling

Common authentication errors:

  • 401 Unauthorized: Invalid or expired session token
  • 403 Forbidden: Invalid verification code or expired WebAuthn challenge
  • 404 Not Found: Email not found (during login) or credential not found

Authentication Required Endpoints

Most API endpoints require authentication. Public endpoints include:

  • GET /health - Health check
  • POST /api/v1/auth/signup - Start signup process
  • POST /api/v1/auth/login - Start login process
  • POST /api/v1/auth/confirm - Verify code
  • POST /api/v1/auth/check-displayname - Check display name availability
  • POST /api/v1/webauthn/login/begin - Begin WebAuthn login
  • POST /api/v1/webauthn/login/finish - Complete WebAuthn login
  • GET /api/v1/assets/* - Public asset browsing (most endpoints)
  • GET /api/v1/seasons/* - Season information

All other endpoints require a valid session token.

Need Help?

If you have questions or need assistance with authentication, please reach out to our support team.