AimableDocs
DocsAPI Reference

Auth

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-proxy/v1.

How to Use the Endpoints

1. Start OIDC Authentication

Initiate the login flow with an OIDC provider.

curl -X GET \
  "https://your-platform.com/api-proxy/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.

curl -X GET \
  "https://your-platform.com/api-proxy/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):

{
  "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.

curl -X POST \
  "https://your-platform.com/api-proxy/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):

{
  "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.

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

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

Success Response (200):

{
  "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.

Authentication & Error Handling

  • Most endpoints do not require a Bearer token, as they are part of the auth flow.
  • The X-API-Key header may be required for service-to-service calls on /v1/refresh.
  • Always handle 422 Validation Error responses:
{
  "detail": [
    {
      "loc": ["query", "code"],
      "msg": "Field required",
      "type": "missing",
      "input": null
    }
  ]
}

Check loc and msg to debug missing or malformed parameters.

Use this domain to securely authenticate users and manage sessions across your applications.

Related Endpoints