API Reference

This document details the public API endpoints for Optare SSO.

Base URL

https://id.optare.one

Authorization

`GET /oauth/authorize`

Initiates the OAuth 2.0 authorization flow.

Query Parameters:

client_id (string, required): Application Client ID.
redirect_uri (string, required): Registered callback URL.
response_type (string, required): Must be code.
scope (string, required): Space-separated scopes (e.g., openid profile).
state (string, recommended): CSRF protection value.
nonce (string, required for OIDC): Replay protection value.
code_challenge (string, optional): PKCE challenge.
code_challenge_method (string, optional): S256 or plain.

Token

`POST /oauth/token`

Exchanges an authorization code or refresh token for access tokens.

Content-Type: application/x-www-form-urlencoded or application/json

Parameters (Authorization Code Grant):

grant_type: authorization_code
code: The authorization code.
redirect_uri: The same URI used in the authorize request.
client_id: Client ID.
client_secret: Client Secret.
code_verifier: PKCE verifier (if challenge was used).

Parameters (Refresh Token Grant):

grant_type: refresh_token
refresh_token: The refresh token.
client_id: Client ID.
client_secret: Client Secret.

Response:

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "id_token": "..."
}

User Info

`GET /oauth/userinfo`

Retrieves profile information for the authenticated user.

Headers:

Authorization: Bearer <access_token>

Response:

{
  "sub": "user_123",
  "name": "John Doe",
  "email": "john@example.com",
  "organizationId": "org_abc",
  "licenses": ["crm"],
  "entitlements": ["crm:read"]
}

Discovery

`GET /.well-known/openid-configuration`

Returns the OpenID Connect discovery document containing all endpoint URLs and supported features.

Public Keys

`GET /.well-known/jwks.json`

Returns the JSON Web Key Set (JWKS) containing the public keys used to verify ID Tokens signed by Optare SSO.

FAQ Custom Claims