Server Tokens

Authenticate server-to-server requests using OAuth client credentials.

This guide walks you through obtaining access tokens for server-to-server authentication using the OAuth 2.0 client credentials flow. This is useful when your backend application needs to call other services or APIs on behalf of itself, without involving a user.

Prerequisites

Before you start, make sure you have:

• A Prelude account with access to Prelude Auth
• An Application ID (appID): see Applications
• Your Management API key for backend calls

How it works

The client credentials flow allows your backend application to:

1. Register an OAuth client (a “service account”) with Prelude Auth
2. Exchange the client credentials (ID and secret) for an access token
3. Use the token to authenticate requests to your backend or other services

This flow is ideal for:

• Service-to-service communication
• Scheduled jobs and background tasks
• Microservices that need to call each other
• API integrations that don’t involve a user

Set up server tokens

1. Register an OAuth client

   Create a new OAuth client registered for the client_credentials grant type:

   curl -X POST https://api.prelude.dev/v2/session/apps/${APP_ID}/oauth/clients \
     -H "Authorization: Bearer ${MANAGEMENT_API_KEY}" \
     -H "Content-Type: application/json" \
     -d '{
       "client_name": "backend-service",
       "redirect_uris": [],
       "provider_url": "https://api.example.com",
       "scopes": ["read", "write"],
       "grant_types": ["client_credentials"]
     }'
   

   The response includes your client_id and client_secret. Store the secret securely, you’ll need it to request tokens. The secret is only returned once, if you lose it, you’ll need to rotate the client.

   Field	Required	Description
   client_name	Yes	A human-readable name for this client (e.g., "backend-service", "background-jobs").
   provider_url	Yes	The URL where your application operates. Used for security validation.
   redirect_uris	No	Can be an empty array for client credentials clients.
   scopes	No	Scopes this client is allowed to request (e.g., ["read", "write"]). Tokens can only request scopes registered for the client.
   grant_types	Yes	For server tokens, use ["client_credentials"].

2. Request an access token

   Exchange your client credentials for an access token:

   curl -X POST https://api.prelude.dev/v1/session/oauth/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d 'grant_type=client_credentials' \
     -d 'client_id=${CLIENT_ID}' \
     -d 'client_secret=${CLIENT_SECRET}' \
     -d 'scope=read write'
   

   Alternatively, use HTTP Basic authentication:

   curl -X POST https://api.prelude.dev/v1/session/oauth/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "Authorization: Basic $(echo -n '${CLIENT_ID}:${CLIENT_SECRET}' | base64)" \
     -d 'grant_type=client_credentials' \
     -d 'scope=read write'
   

   The response contains:

   {
     "access_token": "eyJhbGc...",
     "token_type": "Bearer",
     "expires_in": 3600,
     "scope": "read write"
   }
   

   Parameter	Description
   grant_type	Must be "client_credentials".
   client_id	Your registered client ID.
   client_secret	Your registered client secret. Keep this secure.
   scope	(Optional) Scopes to request. Must be a subset of the scopes registered for your client. If omitted, no scopes are granted.

   Note: Client credentials tokens do not include a refresh_token. When the token expires, request a new one.

3. Use the access token

   Include the token in the Authorization header of your requests:

   curl https://your-backend.example.com/api/resource \
     -H "Authorization: Bearer ${ACCESS_TOKEN}"
   

   On your backend, verify the token signature using the JWKS endpoint. The token’s subject (sub claim) will be the client ID.

Token claims

Tokens issued via client credentials include the following claims:

{
  "sub": "client_id_...",
  "scope": "read write",
  "app_id": "app_...",
  "iat": 1234567890,
  "exp": 1234571490,
  "iss": "https://auth.prelude.dev",
  "aud": "your-app-id"
}

Key differences from user tokens:

• sub is the client ID (not a user ID)
• session_id is absent. There is no session
• Tokens are not revocable via session invalidation
• Tokens expire after 1 hour (configurable)

Client rotation

If you suspect your client secret has been compromised:

1. Create a new client with the same scopes and grant types
2. Update your application to use the new credentials
3. Delete the compromised client using the Management API

curl -X DELETE https://api.prelude.dev/v2/session/apps/${APP_ID}/oauth/clients/${CLIENT_ID} \
  -H "Authorization: Bearer ${MANAGEMENT_API_KEY}"

What’s next?

• Review the token verification guide to validate tokens on your backend
• Set up webhooks if you need to be notified of token-related events
• Explore the Management API for advanced token management