AimableDocs
DocsAPI ReferenceRelease Notes

Auth

Updated 9 July 2026

Authentication (auth)

The auth domain of the Aimable Platform API (v0.1.0) handles user and service authentication using OpenID Connect (OIDC) and token management. It enables secure login flows via third-party identity providers (like Google or Azure AD), session creation, and token refresh mechanisms. This domain is essential for integrating single sign-on (SSO) and maintaining secure, long-lived access to protected resources in multi-tenant environments.

Key Concepts

  • OIDC Provider: An external identity provider (IdP) such as Google, Microsoft, etc., identified by a provider_id (e.g., google, azuread).
  • Frontend Redirect URI: Optional custom redirect URL for the frontend after authentication completes.
  • Session: A server-side session established after successful OIDC flow, used to issue access tokens.
  • Token Refresh: Allows clients to obtain a new access token using a valid refresh token without re-authenticating.

All endpoints are prefixed with /api/v1. The previous /api-proxy prefix remains supported for existing integrations.

How to Use the Endpoints

1. Start OIDC Authentication

Initiate the login flow with an OIDC provider.

bash
curl -X GET \
  "https://your-platform.com/api/v1/auth/oidc/google/start" \
  -H "X-Tenant-Id: tenant-123" \
  -G \
  --data-urlencode "frontend_redirect_uri=https://myapp.com/callback"

Note: This endpoint returns a redirect URL to the provider’s login page. The X-Tenant-Id header is optional but required in multi-tenant setups.

2. Handle OIDC Callback

After the user authenticates with the provider, they are redirected back to this callback endpoint.

bash
curl -X GET \
  "https://your-platform.com/api/v1/auth/oidc/google/callback?code=auth_code_123&state=abcxyz&frontend_redirect_uri=https://myapp.com/callback"

The server validates the code and state, then exchanges them with the provider for tokens. On success, a session is created and the user is redirected to the frontend_redirect_uri.

Success Response (200):

json
{
  "redirect_url": "https://myapp.com/callback?session_id=sess_456"
}

3. Create a Session (OIDC Session)

After authentication, create a persistent session using the received data.

bash
curl -X POST \
  "https://your-platform.com/api/v1/auth/oidc/session" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: abc-123" \
  -d '{
    "provider_id": "google",
    "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxxxx",
    "access_token": "ya29.a0AfBbyxM",
    "expires_in": 3600
  }'

The Idempotency-Key ensures duplicate requests don’t create multiple sessions.

Success Response (200):

json
{
  "session_id": "sess_456",
  "expires_at": "2025-04-05T12:00:00Z"
}

4. Refresh Access Token

Use a valid refresh token to get a new access token.

bash
curl -X POST \
  "https://your-platform.com/api/v1/refresh" \
  -H "Authorization: Bearer <refresh_token>"

Replace <refresh_token> with a valid one issued during login.

Success Response (200):

json
{
  "access_token": "new_access_token_789",
  "token_type": "bearer",
  "expires_in": 3600
}

Error Responses:

  • 401 Unauthorized: Provided token is invalid or expired.
  • 403 Forbidden: Insufficient permissions.
  • 422 Unprocessable Entity: Malformed request.

Common Workflow: User Login via OIDC

  1. Start OIDC Flow
    Call GET /auth/oidc/{provider_id}/start to begin authentication.

  2. User Logs In
    Redirected to provider (e.g., Google). User enters credentials.

  3. Handle Callback
    Provider redirects to GET /auth/oidc/{provider_id}/callback with code and state.

  4. Create Session
    Use POST /auth/oidc/session to finalize session setup.

  5. Access Protected Resources
    Use the issued access token in Authorization: Bearer <token> headers.

  6. Refresh Token When Needed
    Before expiration, call POST /v1/refresh to get a new access token.

See Authentication & errors for request authentication and the standard error responses.

Related Endpoints

See also