Clients

Clients represent applications that can authenticate users via Raha Account’s Identity & Access Management (IAM). A client holds metadata such as redirect URIs, grant/response types, token auth method, and logout settings. On this page, we’ll explore how to query, create, update, rotate secrets for, and delete OIDC clients.

Note: This documentation describes the OpenID Connect (OIDC) implementation for clients in Raha Account’s IAM. For details on OAuth 2.0 client specification, see RFC 6749 Section 2.3: Client Metadata.

The client model

Each client encapsulates OIDC configuration required for your app to perform Authorization Code with PKCE and related flows.

Properties

Name
id
Type
string
Description
Raha Accounts’s unique identifier for the client (internal).
Name
client_name
Type
string
Description
Human-readable application name shown on consent screens.
Name
client_id
Type
string
Description
Public identifier used at the authorization/token endpoints.
Name
client_uri
Type
string
Description
URL to the application's homepage.
Name
logo_uri
Type
string
Description
URL to the application's logo image.
Name
scope
Type
string
Description
Space-separated list of OAuth 2.0 scopes that the client can request.
Name
tos_uri
Type
string
Description
URL to the application's terms of service.
Name
policy_uri
Type
string
Description
URL to the application's privacy policy.
Name
redirect_uris
Type
string[]
Description
Allowed redirect URIs for the client.
Name
token_endpoint_auth_method
Type
string
Description
client_secret_basic | client_secret_post | none.
Name
grant_types
Type
string[]
Description
authorization_code | refresh_token | device_code | client_credentials.
Name
response_types
Type
string[]
Description
code | token.
Name
secret
Type
string | null
Description
Secret for confidential clients. Returned at creation or rotation only; never shown again.
Name
created_at
Type
timestamp
Description
Time the client was created.
Name
updated_at
Type
timestamp
Description
Time the client was last updated.

GET/api/v1/admin/clients

List all clients

Retrieve a paginated list of OIDC clients that you manage.

Optional attributes

Name
pagination[per_page]
Type
integer
Description
Max number of clients per page (default 10).
Name
pagination[page]
Type
integer
Description
Page number to return (default 1).
Name
filter[client_name]
Type
string
Description
Filter by client name.
Name
filter[client_id]
Type
string
Description
Filter by public client identifier.
Name
order[client_name]
Type
string
Description
ASC | DESC. Sort by client name.
Name
order[client_id]
Type
string
Description
ASC | DESC. Sort by client_id.
Name
order[created_at]
Type
string
Description
ASC | DESC. Sort by creation time.
Name
order[updated_at]
Type
string
Description
ASC | DESC. Sort by update time.

Request

GET

/v1/admin/clients

curl -G https://api.account.raha.af/v1/admin/clients \
-H "Authorization: Bearer {token}" \
-d per_page=10 \
-d page=1

Response

{
  "data": [
      {
        "id": "bfb62aa7-52ec-444a-b0b1-7d756a522b0a",
        "client_name": "Movie.af",
        "client_id": "movie-af",
        "client_uri": "https://movie.af",
        "logo_uri": "https://movie.af/logo.png",
        "scope": "openid profile email",
        "tos_uri": "https://movie.af/tos",
        "policy_uri": "https://movie.af/privacy",
        "redirect_uris": [
          "https://movie.af/*"
        ],
        "token_endpoint_auth_method": "none",
        "grant_types": [,
          "authorization_code",
          "refresh_token"
        ],
        "response_types": [
          "code"
        ],
        "created_at": "2025-09-01T12:00:00Z",
        "updated_at": "2025-09-01T12:00:00Z
      },
      {
        "id": "f3be92a2-8649-482d-ac27-ab1912c9b6bd",
        "name": "TMS",
      }
  ],
  "meta": {
    "page": 1,
    "from": 1,
    "to": 10,
    "last_page": 25,
    "per_page": 10,
    "total": 249
  }
}

GET/v1/admin/clients/{id}

Get a client

Retrieve details of a specific OIDC client by its unique ID.

URL parameters

Name
id
Type
string
Description
The unique identifier of the client to retrieve.

Request

GET

/v1/admin/clients/{id}

curl -G https://api.account.raha.af/v1/admin/clients/{id} \
-H "Authorization: Bearer {token}"

Response

{
  "id": "bfb62aa7-52ec-444a-b0b1-7d756a522b0a",
  "client_name": "Movie.af",
  "client_id": "movie-af",
  "client_uri": "https://movie.af",
  "logo_uri": "https://movie.af/logo.png",
  "scope": "openid profile email",
  "tos_uri": "https://movie.af/tos",
  "policy_uri": "https://movie.af/privacy",
  "redirect_uris": [
    "https://movie.af/*"
  ],
  "token_endpoint_auth_method": "none",
  "grant_types": [,
    "authorization_code",
    "refresh_token"
  ],
  "created_at": "2025-09-01T12:00:00Z",
  "updated_at": "2025-09-01T12:00:00Z
}

POST/v1/admin/clients

Create a client

Required attributes

Name
client_name
Type
string
Description
Human-readable application name shown on consent screens.
Name
client_id
Type
string
Description
Public identifier used at the authorization/token endpoints. Must be unique.
Name
client_uri
Type
string
Description
URL to the application's homepage.
Name
logo_uri
Type
string
Description
URL to the application's logo image.
Name
scope
Type
string
Description
Space-separated list of OAuth 2.0 scopes that the client can request.
Name
tos_uri
Type
string
Description
URL to the application's terms of service.
Name
policy_uri
Type
string
Description
URL to the application's privacy policy.
Name
redirect_uris
Type
string[]
Description
Allowed redirect URIs for the client.
Name
token_endpoint_auth_method
Type
string
Description
client_secret_basic | client_secret_post | none.
Name
grant_types
Type
string[]
Description
At least one of:
- authorization_code
- refresh_token
- device_code
- client_credentials
Name
response_types
Type
string[]
Description
At least one of:
- code
- token

Request

POST

/v1/admin/clients

curl -X POST https://api.account.raha.af/v1/admin/clients \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
  "client_name": "Movie.af",
  "client_id": "movie-af",
  "client_uri": "https://movie.af",
  "logo_uri": "https://movie.af/logo.png",
  "scope": "openid profile email",
  "tos_uri": "https://movie.af/tos",
  "policy_uri": "https://movie.af/privacy",
  "token_endpoint_auth_method": "none",
  "redirect_uris": ["https://movie.af/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"]
}'

Response

{
  "id": "bfb62aa7-52ec-444a-b0b1-7d756a522b0a",
  "client_name": "Movie.af",
  "client_id": "movie-af",
  "client_uri": "https://movie.af",
  "logo_uri": "https://movie.af/logo.png",
  "scope": "openid profile email",
  "tos_uri": "https://movie.af/tos",
  "policy_uri": "https://movie.af/privacy",
  "redirect_uris": [
    "https://movie.af/*"
  ],
  "token_endpoint_auth_method": "none",
  "grant_types": [,
    "authorization_code",
    "refresh_token"
  ],
  "response_types": [
    "code"
  ],
  "secret": "xxxxx", // only for CONFIDENTIAL clients
  "created_at": "2025-09-01T12:00:00Z",
  "updated_at": "2025-09-01T12:00:00Z
}

Note: The client secret is returned only at creation time for confidential clients. Store it securely as it will not be shown again.

PUT/v1/admin/clients/{id}

Update a client

Modify an existing OIDC client’s metadata.

URL parameters

Name
id
Type
string
Description
The unique identifier of the client to update.

Updatable attributes

Name
client_name
Type
string
Description
Human-readable application name shown on consent screens.
Name
client_id
Type
string
Description
Public identifier used at the authorization/token endpoints. Must be unique.
Name
client_uri
Type
string
Description
URL to the application's homepage.
Name
logo_uri
Type
string
Description
URL to the application's logo image.
Name
scope
Type
string
Description
Space-separated list of OAuth 2.0 scopes that the client can request.
Name
tos_uri
Type
string
Description
URL to the application's terms of service.
Name
policy_uri
Type
string
Description
URL to the application's privacy policy.
Name
redirect_uris
Type
string[]
Description
Allowed redirect URIs for the client.
Name
token_endpoint_auth_method
Type
string
Description
client_secret_basic | client_secret_post | none.
Name
grant_types
Type
string[]
Description
At least one of:
- authorization_code
- refresh_token
- device_code
- client_credentials
Name
response_types
Type
string[]
Description
At least one of:
- code
- token

Request

PUT

/v1/admin/clients/{id}

curl -X PUT https://api.account.raha.af/v1/admin/clients/{id} \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
  "client_name": "Movie.af Updated",
  "redirect_uris": ["https://movie.af/new-callback"],
  "grant_types": ["authorization_code", "refresh_token"]
}'

Response

Empty

POST/v1/admin/clients/{id}/rotate-secret

Rotate client secret

Generate a new secret for a confidential client. The previous secret is invalidated immediately.

URL parameters

Name
id
Type
string
Description
The unique identifier of the client whose secret to rotate.

Request

POST

/v1/admin/clients/{id}/rotate-secret

curl -X POST https://api.account.raha.af/v1/admin/clients/{id}/rotate-secret \
-H "Authorization: Bearer {token}"

Response

{
  "secret": "new-secret-value"
}

Note: The new client secret is returned only at rotation time. Store it securely as it will not be shown again.

DELETE/v1/admin/clients/{id}

Delete a client

Remove an OIDC client. This action is irreversible.

URL parameters

Name
id
Type
string
Description
The unique identifier of the client to delete.

Request

DELETE

/v1/admin/clients/{id}

curl -X DELETE https://api.account.raha.af/v1/admin/clients/{id} \
-H "Authorization: Bearer {token}"

Response

Empty