API Endpoints Reference

Complete reference for AuthSafe OAuth 2.0 and OpenID Connect endpoints.

REST API

HTTPS Only

OAuth 2.0

Base URL

All endpoints in this page are relative to:

https://identities.authsafe.in

Authorization Endpoint: GET /auth/authorize

Starts the user sign-in flow and returns an authorization code to your redirect URI.

Query Parameters

Parameter	Type	Required	Description
`client_id`	string	Yes	Your application client identifier
`redirect_uri`	string	Yes	Where AuthSafe redirects after sign-in
`response_type`	string	Yes	Use code for authorization code flow
`scope`	string	No	Space-separated scopes, for example openid profile email
`state`	string	Recommended	Opaque value to bind request and callback
`code_challenge`	string	Yes	PKCE challenge value
`code_challenge_method`	string	Yes	Must be S256

Example Request

curl "https://identities.authsafe.in/auth/authorize?client_id=your_client_id&redirect_uri=https://yourapp.com/callback&response_type=code&scope=openid%20profile%20email&state=random_state&code_challenge=CODE_CHALLENGE&code_challenge_method=S256"

Response

https://yourapp.com/callback?code=AUTHORIZATION_CODE&state=random_state

Token Endpoint: POST /auth/token

Exchanges authorization codes, refreshes tokens, or issues client-credentials access tokens.

Request Body Parameters

Parameter	Type	Required	Description
`grant_type`	string	Yes	authorization_code \| refresh_token \| client_credentials
`code`	string	Conditional	Authorization code for authorization_code grant
`refresh_token`	string	Conditional	Refresh token for refresh_token grant
`client_id`	string	Yes	Your application client identifier
`client_secret`	string	Yes	Client secret for confidential clients
`code_verifier`	string	Conditional	PKCE verifier for authorization_code grant

Example Request

curl -X POST https://identities.authsafe.in/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret" \
  -d "code_verifier=CODE_VERIFIER"

Response

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "id_token": "eyJ...",
  "scope": "openid profile email"
}

Additional Routes

GET /auth/user-info

Returns claims for the authenticated user when called with a valid access token.

POST /auth/introspect

Validates token state and metadata according to RFC 7662.

POST /auth/revoke

Revokes access or refresh tokens according to RFC 7009.

GET /auth/logout

Ends the user session and optionally redirects to a post-logout URI.

GET /auth/branding

Returns public branding configuration for a specific client.

/.well-known/*

Provides OIDC discovery metadata and JWKS public keys.

Scope-Dependent Claims

Returned user claims depend on granted scopes. Request profile and email scopes when needed.

Error Responses

AuthSafe returns standard OAuth 2.0 error structures:

{
  "error": "invalid_request",
  "error_description": "Missing required parameter: code_verifier"
}

Error Code	Description
`invalid_request`	Request is malformed or missing a required parameter
`invalid_client`	Client authentication failed
`invalid_grant`	Authorization code or refresh token is invalid or expired
`unauthorized_client`	Client is not allowed to use the requested grant
`unsupported_grant_type`	Grant type is not supported
`invalid_scope`	Requested scope is unknown or not allowed
`access_denied`	Resource owner or authorization server denied the request

Security Considerations

PKCE Is Required

Authorization code flow must include a valid code_challenge and code_verifier pair.

Token Signature Validation

Validate JWT signatures using keys from /.well-known/jwks.json.

Secure Token Storage

Never expose tokens in URLs or logs. Store tokens using secure client and server patterns.

Token Lifetime

Access tokens are short-lived; use refresh tokens for session continuity.

All endpoints require HTTPS. Plain HTTP requests are rejected.

Rate Limiting

Responses include rate-limit headers to help clients throttle and retry safely.

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1234567890

If limits are exceeded, AuthSafe returns HTTP 429 Too Many Requests.

Next Steps

Quick Start Guide

Set up AuthSafe end-to-end with a guided integration path.

View Quick Start ->

Authorization & Access Control

Learn how scopes and role policies map to API access decisions.

Learn About Authorization ->

API Endpoints Reference

Complete reference for AuthSafe OAuth 2.0 and OpenID Connect endpoints.

REST API

HTTPS Only

OAuth 2.0

Base URL

All endpoints in this page are relative to:

https://identities.authsafe.in

Authorization Endpoint: GET /auth/authorize

Starts the user sign-in flow and returns an authorization code to your redirect URI.

Query Parameters

Parameter	Type	Required	Description
`client_id`	string	Yes	Your application client identifier
`redirect_uri`	string	Yes	Where AuthSafe redirects after sign-in
`response_type`	string	Yes	Use code for authorization code flow
`scope`	string	No	Space-separated scopes, for example openid profile email
`state`	string	Recommended	Opaque value to bind request and callback
`code_challenge`	string	Yes	PKCE challenge value
`code_challenge_method`	string	Yes	Must be S256

Example Request

curl "https://identities.authsafe.in/auth/authorize?client_id=your_client_id&redirect_uri=https://yourapp.com/callback&response_type=code&scope=openid%20profile%20email&state=random_state&code_challenge=CODE_CHALLENGE&code_challenge_method=S256"

Response

https://yourapp.com/callback?code=AUTHORIZATION_CODE&state=random_state

Token Endpoint: POST /auth/token

Exchanges authorization codes, refreshes tokens, or issues client-credentials access tokens.

Request Body Parameters

Parameter	Type	Required	Description
`grant_type`	string	Yes	authorization_code \| refresh_token \| client_credentials
`code`	string	Conditional	Authorization code for authorization_code grant
`refresh_token`	string	Conditional	Refresh token for refresh_token grant
`client_id`	string	Yes	Your application client identifier
`client_secret`	string	Yes	Client secret for confidential clients
`code_verifier`	string	Conditional	PKCE verifier for authorization_code grant

Example Request

curl -X POST https://identities.authsafe.in/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret" \
  -d "code_verifier=CODE_VERIFIER"

Response

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "id_token": "eyJ...",
  "scope": "openid profile email"
}

Additional Routes

GET /auth/user-info

Returns claims for the authenticated user when called with a valid access token.

POST /auth/introspect

Validates token state and metadata according to RFC 7662.

POST /auth/revoke

Revokes access or refresh tokens according to RFC 7009.

GET /auth/logout

Ends the user session and optionally redirects to a post-logout URI.

GET /auth/branding

Returns public branding configuration for a specific client.

/.well-known/*

Provides OIDC discovery metadata and JWKS public keys.

Scope-Dependent Claims

Returned user claims depend on granted scopes. Request profile and email scopes when needed.

Error Responses

AuthSafe returns standard OAuth 2.0 error structures:

{
  "error": "invalid_request",
  "error_description": "Missing required parameter: code_verifier"
}

Error Code	Description
`invalid_request`	Request is malformed or missing a required parameter
`invalid_client`	Client authentication failed
`invalid_grant`	Authorization code or refresh token is invalid or expired
`unauthorized_client`	Client is not allowed to use the requested grant
`unsupported_grant_type`	Grant type is not supported
`invalid_scope`	Requested scope is unknown or not allowed
`access_denied`	Resource owner or authorization server denied the request

Security Considerations

PKCE Is Required

Authorization code flow must include a valid code_challenge and code_verifier pair.

Token Signature Validation

Validate JWT signatures using keys from /.well-known/jwks.json.

Secure Token Storage

Never expose tokens in URLs or logs. Store tokens using secure client and server patterns.

Token Lifetime

Access tokens are short-lived; use refresh tokens for session continuity.

All endpoints require HTTPS. Plain HTTP requests are rejected.

Rate Limiting

Responses include rate-limit headers to help clients throttle and retry safely.

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1234567890

If limits are exceeded, AuthSafe returns HTTP 429 Too Many Requests.

Next Steps

Quick Start Guide

Set up AuthSafe end-to-end with a guided integration path.

View Quick Start ->

Authorization & Access Control

Learn how scopes and role policies map to API access decisions.

Learn About Authorization ->