Skip to main content

Clients

A client is an application you register with your Centia.io database so that it can obtain access tokens on behalf of users through OAuth. Every web app, mobile app, server process or CLI that signs users in needs a client: the client_id identifies the application in the authorization flow, and the registered redirect URIs decide where the browser may be sent back with an authorization code.

You create a client once, then use its id when initialising the SDK or building the authorization URL. Public clients, such as single-page and mobile apps, use the Authorization Code flow with PKCE and have no secret; confidential clients run on a server you control and authenticate with a client_secret. This page covers the registration requirements, the security recommendations that follow from the client type, and the API for adding, reading, updating and deleting clients.

Registration Requirements​

  1. Unique Identification

    • Each client must have a unique client_id
    • Provides a distinct identity for your application
    • Used in all OAuth flow interactions

  2. Client Types

    • Confidential Clients

      • Require a client_secret
      • Typically server-side applications
      • Can securely store and manage credentials

    • Public Clients

      • No client_secret
      • Browser-based or mobile applications
      • Must use PKCE (Proof Key for Code Exchange) in Authorization Code Flow

Client ids and secrets​

You can choose the client id or let it be autogenerated (omit the id member). Ids must be unique.

Each client is provided with a secret. The secret is autogenerated and shown when the client is created. It is not possible to retrieve the secret later, so store it safely.

Registration Endpoints​

Register a New OAuth Client
POST https://api.centia.io/api/v4/clients HTTP/1.1
Content-Type: application/json
Authorization: Bearer abc123

{
    "id": "123",
    "name": "rockhall",
    "public": true,
    "redirect_uri": [
        "https://rockhall.io/callback",
        "http://localhost:3000/auth"
    ],
    "description": "Web application for user management",
    "confirm": false,
    "homepage": "https://rockhall.io"
}

Registration Parameters​

  • id: Unique client identifier (if omitted, it will be autogenerated)
  • name: Human-readable name for your client
  • public: Client type (false for confidential, which is default)
  • redirect_uri: Allowed callback URLs
  • description: Optional detailed explanation of the client's purpose
  • homepage: Homepage of the client
  • confirm: Users shall confirm client access in code flow (default: true)
  • two_factor: Users must log in with multi-factor authentication (MFA) (default: true)
  • allow_signup: Allow users to create an account in the web form (default: false)
  • social_signup: Allow users to create an account with social login (default: false)
note

Social signup supports GitHub, GitLab and Google at the moment.

Best Practices​

  1. Secure Redirect URIs: Use HTTPS for web applications
  2. Rotating Credentials: Periodically update client secrets for confidential clients

Security Recommendations​

  • Keep client_secret confidential for confidential clients
  • Implement PKCE for public clients (required in code flow)
  • Revoke clients that are no longer in use

By following these guidelines, you can securely register and manage OAuth clients in Centia.io, ensuring controlled and authorized access to your resources.

Managing Clients​

Add clients​

Create a new client
POST https://api.centia.io/api/v4/clients HTTP/1.1
Content-Type: application/json
Authorization: Bearer abc123

{
    "id": "1",
    "name": "rockhall",
    "public": true,
    "redirect_uri": [
        "https://rockhall.io/callback",
        "http://localhost:3000/auth"
    ],
    "description": "Web application for user management",
    "homepage": "https://rockhall.io",
    "confirm": false,
    "two_factor": true,
    "allow_signup": false,
    "social_signup": false
}
Create multiple clients
POST https://api.centia.io/api/v4/clients HTTP/1.1
Content-Type: application/json
Authorization: Bearer abc123

[
    {
        "id": "1",
        "name": "rockhall",
        "public": true,
        "redirect_uri": [
            "https://rockhall.io/callback",
            "http://localhost:3000/auth"
        ],
        "description": "Web application for awesome stuff",
        "homepage": "https://rockhall.io",
        "confirm": false,
        "two_factor": true,
        "allow_signup": false,
        "social_signup": false
    },
    {
        "id": "2",
        "name": "my second Application",
        "public": false,
        "redirect_uri": [
            "https://myapp.com/callback",
            "http://localhost:3000/auth"
        ],
        "description": "Web application for awesome stuff",
        "homepage": "https://myapp.com",
        "confirm": false,
        "two_factor": true,
        "allow_signup": false,
        "social_signup": false
    }
]
Response
[
    {
        "id": "68932844552b6",
        "secret": "9e46e4b5782546376e784a2c7ccbb8790a57a9a6156ac542b2b3e0e1da024839"
    },
    {
        "id": "6893284485430",
        "secret": "ff4295fdd0a6bb86e1e066cd8c57d9076caf1566fd661ef8a1b3f4a69ab039ed"
    }
]

Get clients​

Get all clients
GET https://api.centia.io/api/v4/clients HTTP/1.1
Accept: application/json
Authorization: Bearer abc123
Get specific clients
GET https://api.centia.io/api/v4/clients/1,2, HTTP/1.1
Accept: application/json
Authorization: Bearer abc123

Update clients​

Update clients
PATCH https://api.centia.io/api/v4/clients/2 HTTP/1.1
Content-Type: application/json
Authorization: Bearer abc123

{
    "redirect_uri": ["https://newapp.com/callback"]
}

Delete clients​

Delete clients
DELETE https://api.centia.io/api/v4/clients/1,2 HTTP/1.1
Authorization: Bearer abc123