API Resources

API Resources (also called Resource Servers) represent the APIs that your OAuth clients access. Each API has an identifier URI, custom scopes, and its own token settings.

Concepts

When an OAuth client requests a token, the resource parameter tells Paylent which API the token is for. This sets the aud (audience) claim in the token, allowing your API to verify that a token was issued specifically for it.

Built-in vs Custom Scopes

Paylent has two types of scopes:

• OIDC scopes (openid, profile, email, offline_access) — Always available. These control protocol-level behavior like ID token contents and refresh token issuance. They don’t require a resource parameter.
• Custom scopes — Defined on an API Resource. When a client requests custom scopes, the resource parameter is required so Paylent knows which API’s scopes to use.

Creating an API Resource

Dashboard

Go to APIs in the OAuth section of the sidebar. Click Create API and configure:

• Name — A display name (e.g. “My Backend API”)
• Identifier — The audience URI (e.g. https://api.yourcompany.com). This cannot be changed after creation.
• Token TTL — How long access tokens last (60–86400 seconds, default 3600)
• Allow offline access — Whether refresh tokens can be issued for this API

Management API

curl -X POST https://acme-test.paylent.com/api/resource-servers \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d '{
    "data": {
      "type": "resource_server",
      "attributes": {
        "name": "My Backend API",
        "identifier": "https://api.yourcompany.com",
        "token_ttl": 3600,
        "allow_offline_access": false
      }
    }
  }'

Adding Scopes

Custom scopes are defined within an API Resource. In the dashboard, open an API and add scopes in the Scopes section.

Scope names are unique per API Resource — the same name (e.g. read:users) can exist on different APIs.

Via Management API

curl -X POST https://acme-test.paylent.com/api/scopes \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d '{
    "data": {
      "type": "scope",
      "attributes": {
        "name": "read:users",
        "description": "Read user profiles"
      },
      "relationships": {
        "resource_server": {
          "data": { "type": "resource_server", "id": "RESOURCE_SERVER_ID" }
        }
      }
    }
  }'

Using the resource Parameter

Authorization Code Flow

When redirecting users to authorize, include the resource parameter to request custom scopes:

GET /oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://myapp.example.com/callback&
  response_type=code&
  scope=openid profile read:users write:users&
  resource=https://api.yourcompany.com&
  code_challenge=CHALLENGE&
  code_challenge_method=S256

The resulting access token will have:

• aud set to https://api.yourcompany.com
• scope including both OIDC and custom scopes
• exp based on the API Resource’s token_ttl

Client Credentials Flow

For machine-to-machine tokens, the resource parameter is always required:

curl -X POST https://acme-test.paylent.com/oauth/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "grant_type=client_credentials&scope=read:users&resource=https://api.yourcompany.com"

Client credentials also require a Client Resource Server Grant linking the client to the API. See OAuth Clients for details.

Token Settings

Each API Resource controls:

Setting	Description	Default
Token TTL	Access token lifetime in seconds	3600 (1 hour)
Allow offline access	Whether refresh tokens are issued	false
Signing algorithm	JWT signing algorithm	RS256

When a token is issued with a resource parameter, these settings override the defaults.

Management API Resource Server

Every environment has a built-in Management API resource server created automatically. It:

• Has 30 scopes matching system permissions (e.g. users:read, clients:write)
• Is marked as a system resource and cannot be edited or deleted
• Has its identifier set to {issuer_url}/api
• Is used to authenticate requests to the /api/* management endpoints

The aud claim in tokens must match the Management API identifier for management requests to be accepted.