API Reference

Complete REST API documentation for integrating with Signify iD.

Base URL

https://api.signifyid.com/v1

Authentication

All API requests require a Bearer token in the Authorization header. Obtain tokens via the OAuth2 flow described in Client Authentication.

Authentication

POST/api/client-auth/login

Initiate Client Login

Initiates the OAuth2 authorization flow for a client application.

Parameters

Name	Type	Required	Description
client_id	string	Required	Your application's Client ID
redirect_uri	string	Required	URL to redirect after authentication
scope	string	Optional	Space-separated list of scopes

Request Body

json

{
  "client_id": "cli_abc123xyz789",
  "redirect_uri": "https://yourapp.com/callback",
  "scope": "openid profile email"
}

Response

json

{
  "authorization_url": "https://signifyid.com/authorize?...",
  "state": "random_state_string"
}

POST/api/client-auth/token

Exchange Code for Tokens

Exchanges an authorization code for access and refresh tokens.

Headers

Name	Value	Description
Content-Type	application/json	Required for JSON body

Request Body

json

{
  "grant_type": "authorization_code",
  "client_id": "cli_abc123xyz789",
  "client_secret": "sec_••••••••••••",
  "code": "auth_code_from_callback",
  "redirect_uri": "https://yourapp.com/callback"
}

Response

json

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

POST/api/client-auth/refresh

Refresh Access Token

Uses a refresh token to obtain a new access token.

Request Body

json

{
  "grant_type": "refresh_token",
  "client_id": "cli_abc123xyz789",
  "client_secret": "sec_••••••••••••",
  "refresh_token": "ref_xyz789abc123..."
}

Response

json

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

POST/api/client-auth/logout

Revoke Session

Revokes the current session and invalidates tokens.

Headers

Name	Value	Description
Authorization	Bearer <access_token>	Current access token

Response

json

{
  "success": true,
  "message": "Session revoked successfully"
}

Sessions

GET/api/sessions/me

Get Current Session

Returns information about the current authenticated session.

Headers

Name	Value	Description
Authorization	Bearer <access_token>	Current access token

Response

json

{
  "session_id": "sess_abc123",
  "user": {
    "id": "usr_xyz789",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "user"
  },
  "device": {
    "browser": "Chrome",
    "os": "Windows 10",
    "ip": "192.168.1.1"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2024-01-16T10:30:00Z"
}

GET/api/sessions

List All Sessions

Returns all active sessions for the current user.

Headers

Name	Value	Description
Authorization	Bearer <access_token>	Current access token

Response

json

{
  "sessions": [
    {
      "id": "sess_abc123",
      "device": "Chrome on Windows",
      "ip": "192.168.1.1",
      "last_active": "2024-01-15T10:30:00Z",
      "is_current": true
    },
    {
      "id": "sess_def456",
      "device": "Safari on iPhone",
      "ip": "192.168.1.2",
      "last_active": "2024-01-14T08:15:00Z",
      "is_current": false
    }
  ]
}

DELETE/api/sessions/{session_id}

Revoke Session

Revokes a specific session by ID.

Parameters

Name	Type	Required	Description
session_id	string	Required	The session ID to revoke

Response

json

{
  "success": true,
  "message": "Session revoked"
}

Users

GET/api/users/me

Get Current User

Returns the authenticated user's profile information.

Headers

Name	Value	Description
Authorization	Bearer <access_token>	Current access token

Response

json

{
  "id": "usr_xyz789",
  "email": "user@example.com",
  "name": "John Doe",
  "avatar_url": null,
  "role": "user",
  "permissions": ["profile:read", "sessions:read"],
  "mfa_enabled": true,
  "created_at": "2024-01-01T00:00:00Z"
}

Error Handling

All API errors follow a consistent format:

Error Response

{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The access token is expired or invalid",
    "status": 401
  }
}

Common Error Codes

Code	Status	Description
INVALID_TOKEN	401	Token is invalid or expired
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
RATE_LIMITED	429	Too many requests
SERVER_ERROR	500	Internal server error