Authentication Guide - Royalti.io API

The Royalti.io API supports multiple authentication methods to suit different integration needs. This guide covers all authentication flows, token management, and best practices.

Authentication Methods

The API supports four authentication token types, each identified by prefix:

1. JWT Tokens (Standard Authentication)

The primary authentication method for user-facing applications. Token Prefixes:

No specific prefix for JWT tokens
Detected by JWT structure (header.payload.signature)

Token Lifecycle:

access_token: Valid for 6 hours
refresh_token: Valid for 1 day

Use Case: Web applications, mobile apps, standard API integrations

2. Workspace API Keys (RWAK)

Programmatic access scoped to a specific workspace. Token Prefix: RWAK Use Case: Server-to-server integrations, automation scripts, CI/CD pipelines

3. User API Keys (RUAK)

Programmatic access scoped to a specific user within a workspace. Token Prefix: RUAK Use Case: User-specific automation, personal integrations

4. God Keys (GODK)

Super admin system access for platform operations. Token Prefix: GODK Use Case: Platform administration, system maintenance (restricted)

God Keys (GODK) provide unrestricted system access and should only be used by authorized platform administrators. Never share or expose God Keys.

JWT Authentication Flow

The standard authentication flow for most applications. Exchange credentials for a refresh token:

curl -X POST "https://api.royalti.io/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password"
  }'

const loginResponse = await fetch('https://api.royalti.io/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'your_password'
  })
});

const { refresh_token, workspaces } = await loginResponse.json();

import requests

response = requests.post(
    'https://api.royalti.io/auth/login',
    json={
        'email': 'user@example.com',
        'password': 'your_password'
    }
)

data = response.json()
refresh_token = data['refresh_token']
workspaces = data['workspaces']

Response:

{
  "message": "Successful",
  "workspaces": [
    {
      "workspaceId": "7bd60554-4f63-4c62-a5f6-c29c3f67cb2a",
      "name": "My Workspace",
      "status": "active",
      "userType": [["Artist"]],
      "role": "admin"
    }
  ],
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

The refresh token is stored in Redis cache for validation. Keep it secure and use it only to obtain access tokens.

Step 2: Get Access Token

Exchange the refresh token and workspace selection for an access token:

curl -X GET "https://api.royalti.io/auth/authtoken?currentWorkspace=WORKSPACE_ID" \
  -H "Authorization: Bearer YOUR_REFRESH_TOKEN"

const tokenResponse = await fetch(
  'https://api.royalti.io/auth/authtoken?currentWorkspace=WORKSPACE_ID',
  {
    headers: {
      'Authorization': `Bearer ${refresh_token}`
    }
  }
);

const { data } = await tokenResponse.json();
const access_token = data.access_token;

response = requests.get(
    'https://api.royalti.io/auth/authtoken',
    params={'currentWorkspace': workspace_id},
    headers={'Authorization': f'Bearer {refresh_token}'}
)

access_token = response.json()['data']['access_token']

Response:

{
  "status": "success",
  "message": "Access token generated for My Workspace",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Step 3: Use Access Token

Include the access token in the Authorization header for all API requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

curl -X GET "https://api.royalti.io/user" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const response = await fetch('https://api.royalti.io/user', {
  headers: {
    'Authorization': `Bearer ${access_token}`
  }
});

response = requests.get(
    'https://api.royalti.io/user',
    headers={'Authorization': f'Bearer {access_token}'}
)

The API supports OAuth login via Google, LinkedIn, and Facebook using Passport.js.

Supported Providers

Google OAuth - /auth/google
LinkedIn OAuth - /auth/linkedin
Facebook OAuth - /auth/facebook

OAuth Flow

Initiate OAuth

Redirect users to the provider’s OAuth endpoint:

GET /auth/google
GET /auth/linkedin
GET /auth/facebook

Users will be redirected to the provider’s login page.

OAuth Callback

After authentication, the provider redirects to our callback URL:

GET /auth/google/callback
GET /auth/linkedin/callback
GET /auth/facebook/callback

The callback exchanges the OAuth code for a session.

Session Cookie

OAuth flows use cookie-based refresh token storage for session management.

Provider Account Linking

Users can link or unlink social providers to their existing account: Get Connected Providers:

GET /auth/social/providers
Authorization: Bearer YOUR_ACCESS_TOKEN

Link a Provider:

POST /auth/social/{provider}/link
Authorization: Bearer YOUR_ACCESS_TOKEN

Unlink a Provider:

DELETE /auth/social/{provider}/unlink
Authorization: Bearer YOUR_ACCESS_TOKEN

Where {provider} is one of: google, facebook, linkedin

Provider Storage

Social provider IDs are stored in the Users table:

googleId - Google account identifier
linkedinId - LinkedIn account identifier
facebookId - Facebook account identifier

API Key Authentication

For programmatic access without user interaction.

Workspace API Keys (RWAK)

Act as the workspace owner within one workspace, limited to the key’s scopes (see below). Token Format: RWAK_xxxxxxxxxxxxxxxx Usage:

curl -X GET "https://api.royalti.io/artist" \
  -H "Authorization: Bearer RWAK_xxxxxxxxxxxxxxxx"

User API Keys (RUAK)

Provide access scoped to a specific user’s permissions within a workspace. Token Format: RUAK_xxxxxxxxxxxxxxxx Usage:

curl -X GET "https://api.royalti.io/user" \
  -H "Authorization: Bearer RUAK_xxxxxxxxxxxxxxxx"

Scopes

A workspace can hold several keys. Each has a label and its own scopes, set when it is created (POST /tenant/apikeys). Only the workspace owner can create a key, because a key acts as the owner:

Scope	Grants
`*`	Full access. Never the default: ask for it explicitly.
`ai:chat`	Roy chat and A2A messages
`ai:tools:read`	Read-only AI tool calls (MCP)
`ai:tools:write`	Mutating AI tool calls (MCP)
`ai:tools:payments:read`	Payment-read AI tools
`publishing:affiliation`	`GET` and `POST /writer/by-user/{tenantUserId}/alltrack/affiliation`, and nothing else

A key without * gets 403 on any route, and any method of a route, that does not admit one of its scopes. Give each integration a key with only the scopes it needs.

Expiry

Keys expire one year after creation unless you choose another date, or choose no expiry at all. To create a key that never expires, send "expiry": null (or "expiry": "never") to POST /tenant/apikeys; omit expiry for the one-year default. A key with no expiry lists with "expiry": null, is never reported as expired and gets no expiry emails, so revoke it when the integration that uses it is retired. Workspace owners are emailed 14 days and 3 days before a key expires, and on each day an expired key is still used. An expired key still works for now, with a Warning: 299 header on every response, but it will soon be refused with 401 and code API_KEY_EXPIRED.

The key is shown once, when it is created. Store it securely like a password. Revoke a key you no longer use with DELETE /tenant/apikeys/{id}.

Token Management

Token Validation

The authentication middleware validates tokens in this order:

Check for Authorization: Bearer <token> header
Detect token type by prefix (RWAK, RUAK, GODK) or structure (JWT)
Validate against Redis cache (for JWT) or database (for API keys)
Decode token and lookup associated TenantUser
Populate req.user with user context

Workspace Switching

Users can switch between workspaces without re-authenticating:

GET /auth/authtoken?currentWorkspace=NEW_WORKSPACE_ID
Authorization: Bearer YOUR_REFRESH_TOKEN

This returns a new access token scoped to the selected workspace.

Token Refresh

When an access token expires (after 6 hours):

{
  "error": {
    "status": 401,
    "message": "JWT token expired"
  }
}

Request a new access token using your refresh token:

GET /auth/authtoken?currentWorkspace=YOUR_WORKSPACE_ID
Authorization: Bearer YOUR_REFRESH_TOKEN

Logout

Invalidate your tokens and end the session:

POST /auth/logout
Authorization: Bearer YOUR_ACCESS_TOKEN

This removes the refresh token from Redis cache and invalidates the session.

Multi-Tenant Architecture

All data in Royalti.io is isolated by tenant (workspace).

Tenant Context

Every resource has a TenantId foreign key
JWT tokens carry activeWorkspace for context
All queries are automatically scoped to the active tenant
Users can belong to multiple tenants with different roles

Custom Domains

Workspaces can use custom domains via Cloudflare SaaS integration:

Custom domain detected in request
Authentication middleware maps domain to workspace
Automatic tenant context without explicit workspace parameter

Password Management

Forgot Password

Request a password reset:

POST /auth/forgotpassword
Content-Type: application/json

{
  "email": "user@example.com",
  "redirect_url": "https://app.royalti.io/reset-password"
}

The response is always 200 with the same body, whether or not the address has an account:

{
  "status": "success",
  "message": "If an account exists for this email, we've sent it a message.",
  "data": null
}

Only a real account is sent the reset link. The link carries the code to pass to /auth/resetpassword.

Reset Password

Reset password with verification code:

PATCH /auth/resetpassword?code=VERIFICATION_CODE
Content-Type: application/json

{
  "email": "user@example.com",
  "new_password": "new_secure_password"
}

A wrong or expired code, and an address with no account, both return 400 Invalid or expired password reset code.

Set Password

For new users who verified their email:

POST /auth/setpassword
Authorization: Bearer VERIFICATION_TOKEN
Content-Type: application/json

{
  "password": "secure_password_123"
}

Magic Link Authentication

Request a passwordless login link:

POST /auth/loginlink
Content-Type: application/json

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

If the address has an account, a login link is sent to it. Clicking the link authenticates the user without a password. The response is the same 200 body as /auth/forgotpassword either way, so it never reveals whether an address has an account.

POST /auth/login likewise returns the same 400 for an unknown address, a wrong password and an account with no password set. Users who signed up with Google, LinkedIn or Facebook have no password: point them to a login link or a password reset.

Best Practices

Security

Use HTTPS Only
- All API requests must use HTTPS
- Verify SSL certificates in production
- Never transmit tokens over HTTP
Secure Token Storage
- Store tokens securely (environment variables, secure vaults)
- Never commit tokens to version control
- Use separate tokens for development and production
Token Rotation
- Implement token refresh logic before expiration
- Handle 401 errors by refreshing tokens
- Re-authenticate if refresh token expires
API Key Management
- Treat API keys like passwords
- Rotate API keys periodically
- Revoke unused or compromised keys immediately

Error Handling

Handle authentication errors gracefully:

async function makeAuthenticatedRequest(url, accessToken, refreshToken) {
  let response = await fetch(url, {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  });

  if (response.status === 401) {
    // Token expired, refresh it
    const newToken = await refreshAccessToken(refreshToken);
    response = await fetch(url, {
      headers: { 'Authorization': `Bearer ${newToken}` }
    });
  }

  return response.json();
}

Rate Limiting

The login endpoint is rate limited:

20 requests per 3 minutes per IP address

Implement exponential backoff for rate limit errors.

Authentication Middleware

Protected routes use two middleware layers:

basicAuth - JWT validation, populates req.user
auditMiddleware - Captures user context (userId, role, IP, user agent)

Some endpoints use enhanced authentication:

enhancedGodminAuth - Supports both GODK and JWT with isAdmin=true
subscriptionMiddleware - Validates plan features and limits

Troubleshooting

Common Issues

401 Unauthorized

Token expired - refresh your access token
Invalid token - verify token is correct and not corrupted
Token not in Redis - re-authenticate to get new tokens

403 Forbidden

Insufficient permissions - check user role and workspace access
Subscription limitation - verify plan includes requested feature

Invalid Workspace

Workspace ID doesn’t exist
User not member of workspace
Workspace is inactive

Debug Tips

Verify token format and structure
Check token expiration timestamps
Confirm workspace ID is correct
Validate user has required permissions
Check Redis connection for JWT validation

Support

For authentication issues or API key requests:

Email: api@royalti.io
Support Center: support.royalti.io
API Status: status.royalti.io

​Authentication Methods

​1. JWT Tokens (Standard Authentication)

​2. Workspace API Keys (RWAK)

​3. User API Keys (RUAK)

​4. God Keys (GODK)

​JWT Authentication Flow

​Step 1: Login

​Step 2: Get Access Token

​Step 3: Use Access Token

​OAuth Social Authentication

​Supported Providers

​OAuth Flow

​Provider Account Linking

​Provider Storage

​API Key Authentication

​Workspace API Keys (RWAK)

​User API Keys (RUAK)

​Scopes

​Expiry

​Token Management

​Token Validation

​Workspace Switching

​Token Refresh

​Logout

​Multi-Tenant Architecture

​Tenant Context

​Custom Domains

​Password Management

​Forgot Password

​Reset Password

​Set Password

​Magic Link Authentication

​Best Practices

​Security

​Error Handling

​Rate Limiting

​Authentication Middleware

​Troubleshooting

​Common Issues

​Debug Tips

​Support

Authentication Methods

1. JWT Tokens (Standard Authentication)

2. Workspace API Keys (RWAK)

3. User API Keys (RUAK)

4. God Keys (GODK)

JWT Authentication Flow

Step 1: Login

Step 2: Get Access Token

Step 3: Use Access Token

OAuth Social Authentication

Supported Providers

OAuth Flow

Provider Account Linking

Provider Storage

API Key Authentication

Workspace API Keys (RWAK)

User API Keys (RUAK)

Scopes

Expiry

Token Management

Token Validation

Workspace Switching

Token Refresh

Logout

Multi-Tenant Architecture

Tenant Context

Custom Domains

Password Management

Forgot Password

Reset Password

Set Password

Magic Link Authentication

Best Practices

Security

Error Handling

Rate Limiting

Authentication Middleware

Troubleshooting

Common Issues

Debug Tips

Support