Server Tokens

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:

Register an OAuth client (a “service account”) with Prelude Auth
Exchange the client credentials (ID and secret) for an access token
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

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"]`.

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.

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:

Create a new client with the same scopes and grant types
Update your application to use the new credentials
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

Documentation

API Reference

Prerequisites

How it works

Set up server tokens

Token claims

Client rotation

What’s next?

​Prerequisites

​How it works

​Set up server tokens

​Token claims

​Client rotation

​What’s next?

Prerequisites

How it works

Set up server tokens

Token claims

Client rotation

What’s next?