Guides
API Reference

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.

IMPORTANT Authentication Method: Optare requires client_secret_post authentication. Send client_id and client_secret in the POST body, NOT in the Authorization header.

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 (must be in POST body).
  • client_secret: Client Secret (must be in POST body).
  • 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 (must be in POST body).
  • client_secret: Client Secret (must be in POST body).

Example Request:

curl -X POST https://id.optare.one/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=auth_xxx" \
  -d "redirect_uri=http://localhost:3000/callback" \
  -d "client_id=your-client-id" \
  -d "client_secret=your-client-secret" \
  -d "code_verifier=your-verifier"

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.

FAQCustom Claims