Authentication

GET/api/v1/admin/interactions/start

1) Start interaction

Begin by initiating an interaction start request to get the context for user authentication.

Attributes

  • Name
    client_id
    Type
    string
    Description

    Your registered client ID.

  • Name
    redirect_uri
    Type
    string
    Description

    The redirect URI registered with the client.

  • Name
    scope
    Type
    string
    Description

    Space-separated list of requested scopes (e.g., openid profile email).

  • Name
    state
    Type
    string
    Description

    Opaque value to maintain state between the request and callback.

  • Name
    nonce
    Type
    string
    Description

    Opaque value to associate a client session with an ID token.

  • Name
    code_challenge
    Type
    string
    Description

    Base64url-encoded SHA256 hash of the code verifier.

  • Name
    code_challenge_method
    Type
    string
    Description

    Must be "S256" to indicate SHA256 is used.

  • Name
    prompt
    Type
    string
    Description

    Optional. Can be "login" to force re-authentication or "consent" to prompt for consent.

  • Name
    acr_values
    Type
    string
    Description

    Optional. Authentication Context Class Reference values to specify required authentication methods. AAL1, AAL2 for different assurance levels.

  • Name
    session_id
    Type
    string
    Description

    Optional. Existing session ID to continue an authenticated session.

Note: The interaction start endpoint is typically called server-side after the user is redirected to the authorization URL. It provides the necessary context to render the login form and proceed with authentication.

Request

GET
/api/v1/oauth/interactions/start
curl -G "https://api.account.af/api/v1/oauth/interactions/start" \
  --data-urlencode "client=YOUR_CLIENT_ID" \
  --data-urlencode "redirect_uri=https://app.example.com/callback" \
  --data-urlencode "response_type=code" \
  --data-urlencode "scope=openid profile email" \
  --data-urlencode "code_challenge=BASE64URL_SHA256_OF_CODE_VERIFIER" \
  --data-urlencode "code_challenge_method=S256" \
  --data-urlencode "state=RANDOM" \
  --data-urlencode "nonce=RANDOM" \
  --data-urlencode "prompt=login" \
  --data-urlencode "acr_values=AAL1"

Response

{
  "auth_handle": "bfb62aa7-52ec-444a-b0b1-7d756a522b0b" ;
  "expires_at": "2024-10-01T12:00:00Z";
  "next": "AUTHORIZE"; // "MFA" | "CONSENT" | "LOGIN"
  "redirect_to"?: "https://app.example.com/callback?code=AUTH_CODE&state=RANDOM";
}
POST/api/v1/oauth/interactions/:id/login

2) Interaction Login

Submit user credentials to authenticate. On success, you will receive a redirect URL with an authorization code.

Body Parameters

  • Name
    user_identifier
    Type
    string
    Description

    The type of identifier being used (e.g., "email" or "username" or "phone_number").

  • Name
    identifier
    Type
    string
    Description

    The user's login identifier (e.g., email or username).

  • Name
    password
    Type
    string
    Description

    The user's password.

Request

POST
/api/v1/oauth/interactions/:id/login
curl -X POST https://auth.example.com/api/v1/oauth/interactions/INTERACTION_ID/login \
  -H "Content-Type: application/json" \
  -d '{"user_identifier":"email","identifier":"dev@mohsenamani.com","password":"correcthorsebatterystaple"}'

Response

{
  "next": "AUTHORIZE"; // "MFA" | "CONSENT"
  redirectTo: "https://app.example.com/callback?code=AUTH_CODE&state=RANDOM";
  allowedFactors: ["totp", "sms"]; // if next is "MFA"
  challengeId?: "uuid-of-challenge"; // if next is "MFA"
}
POST/api/v1/oauth/token

3) Token Exchange

Exchange the authorization code for tokens using the original code verifier.

Body Parameters

  • Name
    grant_type
    Type
    string
    Description

    Must be "authorization_code" for this flow.

  • Name
    code
    Type
    string
    Description

    The authorization code received from the interaction login step.

  • Name
    redirect_uri
    Type
    string
    Description

    Must match the redirect URI used in the authorization request.

  • Name
    code_verifier
    Type
    string
    Description

    The original code verifier used to generate the code challenge.

  • Name
    client_id
    Type
    string
    Description

    Your registered client ID.

Request

POST
/api/v1/oauth/token
curl -X POST https://auth.example.com/api/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE_HERE" \
  -d "redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback" \
  -d "code_verifier=YOUR_CODE_VERIFIER" \
  -d "client_id=YOUR_CLIENT_ID"

Response

{
  "access_token": "XXXXX",
  "id_token": "XXXXX",
  "refresh_token": "XXXXX",
}
POST/api/v1/oauth/token

4) Refresh Token

Use the refresh token to obtain new access and ID tokens when the current access token expires.

Parameters

  • Name
    grant_type
    Type
    string
    Description

    Must be "refresh_token" for this flow.

  • Name
    client_id
    Type
    string
    Description

    Your registered client ID.

Note: Refresh tokens are stored in cookies and sent automatically with requests.

Request

POST
/api/v1/oauth/token
curl -X POST https://auth.example.com/api/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID

Response

{
  "access_token": "NEW_XXXXX",
  "id_token": "NEW_XXXXX",
  "refresh_token": "NEW_XXXXX",
}
POST/api/v1/oauth/token

5) Client Credential Exchange

Use the client credentials to obtain new access for the client application access.

Parameters

  • Name
    grant_type
    Type
    string
    Description

    Must be "client_credentials" for this flow.

  • Name
    client_id
    Type
    string
    Description

    Your registered client ID.

  • Name
    client_secret
    Type
    string
    Description

    Your registered client secret.

  • Name
    scope
    Type
    string[]
    Description

    Space-separated list of requested scopes (e.g., openid profile email).

Request

POST
/api/v1/oauth/token
curl -X POST https://auth.example.com/api/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID
  -d "client_secret=YOUR_CLIENT_SECRET
  -d "scope=["openid"]

Response

{
  "access_token": "NEW_ACCESS_TOKEN",
  "expires_in": 3600,
  "token_type": "Bearer"
}
GET/.well-known/openid-configuration

7) Configuration Discovery

Fetch the OIDC configuration to discover endpoints and supported features.

No parameters required.

Request

GET
/.well-known/openid-configuration
curl -X GET https://auth.example.com/.well-known/openid-configuration

Response

{
  issuer: "https://auth.example.com",
  authorization_endpoint: "https://auth.example.com/api/v1/oauth/authorize",
  token_endpoint: "https://auth.example.com/api/v1/oauth/token",
  userinfo_endpoint: "https://auth.example.com/api/v1/oauth/userinfo",
  jwks_uri: "https://auth.example.com/.well-known/jwks.json",
  end_session_endpoint: "https://auth.example.com/api/v1/oauth/logout",
  introspection_endpoint: "https://auth.example.com/api/v1/oauth/introspect",
  revocation_endpoint: "https://auth.example.com/api/v1/oauth/revoke",
  device_authorization_endpoint: "https://auth.example.com/api/v1/oauth/device_authorize",
  check_session_iframe: "https://auth.example.com/api/v1/oauth/check_session",
  scopes_supported: ["openid", "profile", "email"],
  response_types_supported: ["code", "token", "id_token"],
  response_modes_supported: ["query", "fragment", "form_post"],
  grant_types_supported: ["authorization_code", "refresh_token"],
  subject_types_supported: ["public"],
  id_token_signing_alg_values_supported: ["RS256"],
  userinfo_signing_alg_values_supported: ["RS256"],
  code_challenge_methods_supported: ["S256"],
  claims_supported: ["sub", "iss", "aud", "exp", "iat", "name", "email"],
  acr_values_supported?: ["AAL1", "AAL2"];
  amr_values_supported?: ["pwd", "mfa"];
}
GET/.well-known/jwks.json

6) JWKS

Fetch the JSON Web Key Set (JWKS) to validate tokens.

No parameters required.

Request

GET
/api/v1/oauth/jwks
curl -X GET https://auth.example.com/.well-known/jwks.json

Response

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "key-id",
      "use": "sig",
      "alg": "RS256",
      "n": "modulus",
      "e": "exponent"
    }
  ]
}

Was this page helpful?