Skip to main content
POST
/
v1
/
auth
/
clients
Create Client
curl --request POST \
  --url https://api.example.com/v1/auth/clients \
  --header 'Content-Type: application/json' \
  --data '
{
  "realm_id": "<string>",
  "redirect_uris": [
    {}
  ]
}
'
{
  "client_id": "<string>",
  "client_secret": "<string>",
  "realm_id": "<string>",
  "redirect_uris": [
    {}
  ],
  "error": "<string>"
}

​
Overview

Clients represent applications that can authenticate users within a realm. Each client receives a unique client_id and client_secret which must be provided during the login flow. This ensures only authorized applications can request tokens.

​
Request Body

​
realm_id
string
required
The realm identifier where this client will be registered.
​
redirect_uris
array
required
Array of allowed redirect URIs for OAuth flows. Used for security validation in authorization code flows.

​
Response

Returns the created client with generated credentials:
​
client_id
string
Auto-generated UUID serving as the client identifier.
​
client_secret
string
Auto-generated UUID serving as the client secret. Store this securely.
​
realm_id
string
The realm this client belongs to.
​
redirect_uris
array
Array of allowed redirect URIs.

​
Example

cURL
curl -X POST http://localhost:8080/v1/auth/clients \
  -H 'Content-Type: application/json' \
  -d '{
    "realm_id": "acme",
    "redirect_uris": [
      "https://app.acme.com/callback",
      "http://localhost:3000/callback"
    ]
  }'
Response
{
  "client_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "client_secret": "a1b2c3d4-e5f6-4a5b-8c7d-9e8f7a6b5c4d",
  "realm_id": "acme",
  "redirect_uris": [
    "https://app.acme.com/callback",
    "http://localhost:3000/callback"
  ]
}

​
Security Notes

The client_secret is only returned once during creation. Store it securely in your application’s configuration. If lost, you must create a new client.
  • Use the client_id and client_secret in all token requests for this realm
  • Redirect URIs provide security validation for OAuth flows
  • Each client is scoped to a single realm

​
Error Responses

​
error
string
Human-readable error message when the request fails.
Common errors:
  • 400 Bad Request: Invalid request format or missing required fields
  • 404 Not Found: Realm does not exist
  • 500 Internal Server Error: Client creation failed due to internal error

Build docs developers (and LLMs) love

Get started for freeTalk to us