Skip to main content

Clients

OAuth clients are applications that request and manage access to user resources through the OAuth authorization protocol. These clients act as intermediaries, enabling secure, delegated access to user accounts without directly handling sensitive credentials.

Client Registration Process​

Registering an OAuth client in Centia is a crucial step to enable secure, authorized access to your resources. The registration process involves creating a unique client identity that will be used for authentication and authorization.

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 is shown when creating the client. It is not possible to retrieve the secrete after creation, so keep it save.

Registration Endpoints​

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

{
    "name": "My Application",
    "public": true,
    "redirect_uri": [
        "https://myapp.com/callback",
        "http://localhost:3000/auth"
    ],
    "description": "Web application for user management",
    "confirm": false,
    "homepage": "https://myapp.com"
}

Key Registration Parameters​

  • name: Human-readable name for your client
  • public: Client type (false for confidential)
  • redirect_uri: Allowed callback URLs
  • description: Optional detailed explanation of the client's purpose
  • confirm: Users shall confirm client access in code flow
  • homepage: Homepage of the client

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
  • Monitor and audit client activities
  • Revoke clients that are no longer in use

By following these guidelines, you can securely register and manage OAuth clients in the Centia ecosystem, 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 <access_token>

{
    "name": "My Application",
    "public": true,
    "redirect_uri": [
    "https://myapp.com/callback",
    "http://localhost:3000/auth"
    ],
    "description": "Web application for user management",
    "confirm": false,
    "homepage": "https://myapp.com"
}
Create multiple clients
POST https://api.centia.io/api/v4/clients HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access_token>

[
    {
        "name": "My first Application",
        "public": true,
        "redirect_uri": [
            "https://myapp.com/callback",
            "http://localhost:3000/auth"
        ],
        "description": "Web application for awesome stuff",
        "confirm": false,
        "homepage": "https://myapp.com"
    },
    {
        "name": "My second Application",
        "public": false,
        "redirect_uri": [
            "https://myapp.com/callback",
            "http://localhost:3000/auth"
        ],
        "description": "Web application for awesome stuff",
        "confirm": false,
        "homepage": "https://myapp.com"
    }
]
Response
{
    "clients": [
        {
            "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 <access_token>
Update Client Configuration
PATCH https://api.centia.io/api/v4/oauth/clients/<client_id> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access_token>

    {
        "redirect_uris": ["https://newapp.com/callback"]
    }
Revoke Client
DELETE https://api.centia.io/api/v4/oauth/clients/<client_id> HTTP/1.1
Authorization: Bearer <access_token>

Update clients​

Update client
PATCH https://api.centia.io/api/v4/clients/<client_id> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access_token>

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

Delete clients​

Delete client
DELETE https://api.centia.io/api/v4/clients/<client_id> HTTP/1.1
Authorization: Bearer <access_token>