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.

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 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: Users can sign up for a new account in the web-form (default: false)
  • social_signup: Users can sign up for a new account with social login. (default: false)

Note:

  • Social signup only supports GitHub 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
{
    "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 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_uris": ["https://newapp.com/callback"]
}

Delete clients​

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