Clients

A client represents a machine identity in Roled. Where users are humans who log in through a browser, clients are backend services, APIs, or automation scripts that communicate directly with Roled using client credentials.

What Is a Client?

A client is used for server-to-server or machine-to-machine communication. It authenticates using the OAuth 2.0 Client Credentials Flow and receives a JWT access token that represents the client’s identity.

Typical use cases include:

• Your backend API calling Roled to manage users
• A CI/CD pipeline creating or deactivating users programmatically
• A scheduled job syncing data between your system and Roled
• A microservice checking user permissions on every request

How Clients Differ from Users

The Default Client

Every project in Roled automatically includes one default client. This client is ready to use immediately after creating a project.

The default client has the following characteristics:

• Created automatically with every new project
• Supports both Authorization Code and Client Credentials flows
• Can be disabled
• Cannot be deleted

You can use the default client for most scenarios. Create additional clients when you need different permission sets for different services.

Client Credentials and Security

A client authenticates using HTTP Basic Authentication with its client_id and client_secret:

Authorization: Basic base64(client_id:client_secret)

Keep your client secret safe. Treat it like a password. Never expose it in frontend code or public repositories.

Assigning Permissions to a Client

Unlike users (who get permissions through a role), permissions are assigned directly to a client. This gives you precise control over what each service is allowed to do.

    graph LR
    C["Client: Backend Service"] --> P1["users:read"]
    C --> P2["users:create"]
    C --> P3["users:update"]
    C --> P4["roles:read"]
  

Creating a Client

You always have the default client available. Use the following request to create additional clients:

curl --request POST \
  --url https://auth.roled.id/api/v1/projects/2JUSLUee46xG6iEwG8JwPc/clients \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJo...' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Backend Service",
    "description": "Server-side service for automated user and role management",
    "permission_ids": [
      "2JRjbZKS7hDLRWp2jzaevn",
      "2JRjbZKS7h72qSpPAJBuSj",
      "2JRjbZKS7hJfHq9yRzVqhV",
      "2JRjbZKS7feihqSQx5D8yf"
    ]
  }'

Response:

{
  "success": true,
  "data": {
    "id": "2JUV7yC7gWEuzu8BTEXoY5",
    "created_at": "2026-07-16T14:30:00Z",
    "updated_at": "2026-07-29T08:30:00Z",
    "name": "Backend Service",
    "description": "Server-side service for automated user and role management",
    "is_default": false,
    "is_active": true,
    "permissions": [
      {
        "id": "2JRjbZKS7hDLRWp2jzaevn",
        "resource_name": "Users",
        "permission_name": "Create"
      },
      {
        "id": "2JRjbZKS7h72qSpPAJBuSj",
        "resource_name": "Users",
        "permission_name": "Read"
      },
      {
        "id": "2JRjbZKS7hJfHq9yRzVqhV",
        "resource_name": "Users",
        "permission_name": "Update"
      },
      {
        "id": "2JRjbZKS7feihqSQx5D8yf",
        "resource_name": "Roles",
        "permission_name": "Read"
      }
    ]
  }
}

Authenticating as a Client

Use the Client Credentials flow to obtain an access token:

# Encode credentials as Base64
# base64("client_id:client_secret")

curl --request POST \
  --url https://auth.roled.id/api/v1/tokens \
  --header 'Authorization: Basic MkpVjd5QzdnV0V1enU4QlRFWG9ZNTpzZWNfQmFja...' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials'

Response:

{
    "success": true,
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJo...",
        "expires_in": 3600,
        "token_type": "bearer"
    }
}

Client Token Claims

The JWT issued for a client contains a cid (client ID) claim:

{
  "iss": "https://auth.roled.id",
  "sub": "<client_id>",
  "aud": "<project_id>",
  "jti": "<token_id>",
  "cid": "<client_id>",
  "iat": 1753780300,
  "exp": 1753866700
}

The sub and cid claims are the same and represent the client ID. There is no uid claim in client tokens, because no user is involved.

Key Points

• Clients are machine identities — backend services, scripts, and APIs.
• Clients authenticate using client_id + client_secret (Client Credentials flow).
• Permissions are assigned directly to clients, not through roles.
• Every project has a default client created automatically.
• Client JWTs contain a cid claim, without uid.