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.

Additional API service: Email Verification is available as a separate metered API service for subscribed tenants. Usage is tracked per tenant and documented below.
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

POST /api/verify/email

Email Verification is a separate API service that validates syntax, checks DNS reachability, and detects disposable email domains. Requests require a valid bearer token issued by Ailacs Identity.

Authentication

Include the bearer token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Example Request

POST /api/verify/email HTTP/1.1
Host: auth.ailacs.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "email": "user@example.com"
}

Success Response

{
  "email": "user@example.com",
  "valid": true,
  "syntax_valid": true,
  "domain_exists": true,
  "is_disposable": false,
  "checked_at": "2026-01-01T12:00:00Z"
}
Field Description
valid True when all validation checks pass.
syntax_valid The email address conforms to valid syntax.
domain_exists The domain resolves in DNS.
is_disposable The domain is on the disposable email provider list.
checked_at UTC timestamp when verification completed.

Error Responses

Status Error Code Description
400 invalid_request The email payload is missing or invalid.
401 invalid_token The bearer token is missing, expired, or invalid.
429 api_limit_exceeded The subscription has reached its monthly API call limit.

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