API Reference

Complete documentation for Ailacs Identity OpenID Connect endpoints.

Quick Navigation

Overview

Ailacs Identity implements the OpenID Connect and OAuth 2.0 protocols, providing secure authentication and authorization for your applications. All endpoints follow industry standards and are compatible with standard OIDC client libraries.

Base URL: https://identity.yourdomain.com

Supported Grant Types

  • Authorization Code: For web applications with server-side code
  • Password (Resource Owner): For trusted first-party applications
  • Client Credentials: For machine-to-machine authentication

GET/POST /connect/authorize

The authorization endpoint is used to interact with the end-user and obtain authorization. This is the starting point for the Authorization Code flow.

Parameters

Parameter Type Required Description
client_id string Yes The client identifier issued during registration
redirect_uri string Yes URI where the user will be redirected after authorization
response_type string Yes Value must be code for authorization code flow
scope string Yes Space-separated list of scopes (e.g., openid profile email)
state string Recommended Opaque value used to maintain state between request and callback
prompt string No Special values: create (user registration), tenant_create (tenant registration)

Example Request

GET /connect/authorize?
  client_id=your_client_id&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=openid%20profile%20email&
  state=abc123
Host: identity.yourdomain.com

Response

On success, the user is redirected to the redirect_uri with an authorization code:

HTTP/1.1 302 Found
Location: https://yourapp.com/callback?
  code=AUTH_CODE_HERE&
  state=abc123
Note: If the user is not authenticated, they will be redirected to the login page. After authentication, they'll be redirected back to complete the authorization flow.

POST /connect/token

The token endpoint is used to obtain access tokens and ID tokens. This endpoint supports multiple grant types.

Grant Type: Authorization Code

Exchange an authorization code for tokens.

Parameters

Parameter Type Required Description
grant_type string Yes Value must be authorization_code
code string Yes The authorization code received from /connect/authorize
redirect_uri string Yes Must match the redirect_uri from the authorization request
client_id string Yes Your application's client identifier
client_secret string Yes Your application's client secret

Example Request

POST /connect/token HTTP/1.1
Host: identity.yourdomain.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTH_CODE_HERE&
redirect_uri=https://yourapp.com/callback&
client_id=your_client_id&
client_secret=your_client_secret

Grant Type: Password (Resource Owner)

Authenticate with username and password. Only use for trusted first-party applications.

Parameters

Parameter Type Required Description
grant_type string Yes Value must be password
username string Yes The user's username or email
password string Yes The user's password
client_id string Yes Your application's client identifier
client_secret string Yes Your application's client secret
scope string No Space-separated list of scopes

Example Request

POST /connect/token HTTP/1.1
Host: identity.yourdomain.com
Content-Type: application/x-www-form-urlencoded

grant_type=password&
username=user@example.com&
password=SecurePassword123&
client_id=your_client_id&
client_secret=your_client_secret&
scope=openid%20profile

Grant Type: Client Credentials

Authenticate for machine-to-machine scenarios without user context.

Parameters

Parameter Type Required Description
grant_type string Yes Value must be client_credentials
client_id string Yes Your application's client identifier
client_secret string Yes Your application's client secret
scope string No Space-separated list of scopes

Example Request

POST /connect/token HTTP/1.1
Host: identity.yourdomain.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=your_client_id&
client_secret=your_client_secret&
scope=api

Success Response

All grant types return a similar response structure:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "openid profile email"
}
Field Description
access_token JWT token used to access protected resources
token_type Always "Bearer"
expires_in Token lifetime in seconds
id_token JWT containing user identity claims (only with openid scope)
scope Granted scopes

GET/POST /connect/userinfo

The UserInfo endpoint returns claims about the authenticated user. This endpoint requires a valid access token.

Authentication

Include the access token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Example Request

GET /connect/userinfo HTTP/1.1
Host: identity.yourdomain.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Success Response

{
  "sub": "507f1f77bcf86cd799439011",
  "name": "john.doe",
  "role": ["user", "admin"]
}
Claim Description
sub Subject identifier (unique user ID)
name User's username
role Array of user roles

GET/POST /connect/logout

The logout endpoint terminates the user's session and optionally redirects to a specified URI.

Parameters

Parameter Type Required Description
post_logout_redirect_uri string No URI to redirect to after logout. Must be pre-registered.

Example Request

GET /connect/logout?
  post_logout_redirect_uri=https://yourapp.com/logged-out
Host: identity.yourdomain.com

Response

The user's session is terminated and they are redirected to the specified URI or the default landing page.

HTTP/1.1 302 Found
Location: https://yourapp.com/logged-out

Error Codes

All endpoints follow the OAuth 2.0 error response format. Errors are returned as JSON with the following structure: 

{
  "error": "invalid_grant",
  "error_description": "The username/password couple is invalid."
}

Common Error Codes

Error Code Description
invalid_request The request is missing a required parameter or is malformed
invalid_client Client authentication failed
invalid_grant The provided authorization grant is invalid, expired, or revoked
unauthorized_client The client is not authorized to use this grant type
unsupported_grant_type The grant type is not supported by the server
invalid_scope The requested scope is invalid or unknown
access_denied The user or authorization server denied the request

Need Help?

Our support team is here to help you integrate Ailacs Identity into your application.

Contact Support