API Reference

OAuth 2.0

TigerIdentity implements OAuth 2.0 for secure authorization. Support for Client Credentials and Authorization Code flows with JWT access tokens and refresh tokens.

Get StartedAuthentication
OAuth Base URL: https://api.tigeridentity.com/v1/oauth

Overview

OAuth 2.0 is the industry-standard protocol for authorization. TigerIdentity supports two flows optimized for different use cases:

Client Credentials

Server-to-server authentication for machine clients. No user interaction required. Ideal for backend services and automated workflows.

Authorization Code

User-authorized access with consent flow. Secure for web and mobile applications that act on behalf of users.

Client Credentials Flow

Use this flow for machine-to-machine authentication where no user is involved. Your application exchanges client credentials for an access token.

1

Register OAuth Client

First, register your application in the TigerIdentity dashboard to obtain client credentials.

{
  "client_id": "oauth_client_abc123xyz789",
  "client_secret": "secret_def456uvw012",
  "grant_types": ["client_credentials"],
  "redirect_uris": []
}
2

Request Access Token

POST/oauth/token

Exchange client credentials for access token

Request

curl -X POST \
  "https://api.tigeridentity.com/v1/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "oauth_client_abc123xyz789",
    "client_secret": "secret_def456uvw012",
    "scope": "read:principals write:policies"
  }'

Parameters

grant_typestring (required)

Must be "client_credentials"

client_idstring (required)

Your OAuth client ID

client_secretstring (required)

Your OAuth client secret

scopestring (optional)

Space-separated list of scopes

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:principals write:policies",
  "created_at": 1707136800
}
Token expires in 1 hour (3600 seconds)
No refresh token in client_credentials flow
Token is a signed JWT
3

Use Access Token

Include the access token in the Authorization header for all API requests.

curl -X GET \
  "https://api.tigeridentity.com/v1/principals" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ..." \
  -H "Content-Type: application/json"

Authorization Code Flow

Use this flow for user-authorized access. The user grants permission through a consent screen, and your application receives an authorization code to exchange for tokens.

1

Request Authorization

GET/oauth/authorize

Redirect user to TigerIdentity authorization page

Authorization URL

https://api.tigeridentity.com/v1/oauth/authorize?
  response_type=code&
  client_id=oauth_client_abc123xyz789&
  redirect_uri=https://yourapp.com/callback&
  scope=read:principals%20write:policies&
  state=random_state_string

Query Parameters

response_typestring (required)

Must be "code"

client_idstring (required)

Your OAuth client ID

redirect_uristring (required)

Must match a registered redirect URI

scopestring (optional)

Space-separated list of scopes

statestring (recommended)

Random string for CSRF protection

2

Exchange Authorization Code

POST/oauth/token

Exchange authorization code for tokens

Request

curl -X POST \
  "https://api.tigeridentity.com/v1/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "auth_code_xyz789abc123",
    "client_id": "oauth_client_abc123xyz789",
    "client_secret": "secret_def456uvw012",
    "redirect_uri": "https://yourapp.com/callback"
  }'

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_abc123def456ghi789",
  "scope": "read:principals write:policies",
  "created_at": 1707136800
}
3

Refresh Access Token

Request

curl -X POST \
  "https://api.tigeridentity.com/v1/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "rt_abc123def456ghi789",
    "client_id": "oauth_client_abc123xyz789",
    "client_secret": "secret_def456uvw012"
  }'

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_new789xyz456abc123",
  "scope": "read:principals write:policies"
}

JWT Token Format

Access tokens are signed JWTs (JSON Web Tokens) containing claims about the authenticated principal and granted scopes.

Token Structure (Decoded)

{
  "header": {
    "alg": "RS256",
    "typ": "JWT",
    "kid": "key_1"
  },
  "payload": {
    "iss": "https://api.tigeridentity.com",
    "sub": "principal_abc123",
    "aud": "https://api.tigeridentity.com",
    "exp": 1707140400,
    "iat": 1707136800,
    "scope": "read:principals write:policies",
    "client_id": "oauth_client_abc123xyz789"
  },
  "signature": "..."
}

Claims Description

iss

Token issuer (TigerIdentity)

sub

Subject (principal ID)

aud

Intended audience

exp

Expiration time (Unix timestamp)

iat

Issued at time (Unix timestamp)

scope

Granted permissions

Token Validation

# Verify token signature using public keys from JWKS endpoint
GET https://api.tigeridentity.com/v1/oauth/.well-known/jwks.json

# Response contains public keys for signature verification
{
  "keys": [
    {
      "kty": "RSA",
      "kid": "key_1",
      "use": "sig",
      "alg": "RS256",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

OAuth Scopes

Scopes define the permissions granted to an access token. Request only the scopes your application needs.

read:principals

Read principal information

write:principals

Create and modify principals

delete:principals

Delete principals

read:policies

Read policy definitions

write:policies

Create and modify policies

delete:policies

Delete policies

evaluate:decisions

Evaluate access decisions

read:audit

Read audit logs

admin:all

Full administrative access

Tip: Use space-separated scope strings in requests:"read:principals write:policies"

Related Documentation

Authentication

Complete authentication guide including API keys and token management.

Learn more

Go SDK

OAuth 2.0 client implementation with automatic token refresh.

Learn more

Security Best Practices

Learn how to securely implement OAuth 2.0 flows in your application.

Learn more

Ready to implement OAuth 2.0?

Register your OAuth client and start building secure integrations.

Get StartedQuick Start Guide