API Overview | Sigma Auth

Interactive API Reference

View the full interactive OpenAPI documentation at auth.sigmaidentity.com/api/auth/reference

Sigma Auth provides a comprehensive OAuth 2.0/OIDC compliant API for Bitcoin-based authentication. All endpoints support standard OAuth flows while adding Bitcoin cryptographic verification.

Base URL

All API endpoints are available at:

https://auth.sigmaidentity.com

Authentication Methods

OAuth 2.0 Flow (Recommended)

Standard OAuth 2.0 authorization code flow with PKCE support.

Direct Bitcoin Authentication

Direct signature-based authentication using the /sigma/authorize endpoint.

Access Tokens

Authorization: Bearer <your_access_token>

Format: JWT (ES256 signed)
Lifetime: 30 days
Works across all client applications

No refresh tokens - when tokens expire, users re-authenticate through the OAuth flow.

Quick Reference

Core Endpoints

GET /oauth2/authorize - Start OAuth flow (custom gate)
POST /api/auth/oauth2/token - Exchange code for token
GET /api/auth/oauth2/userinfo - Get user information
POST /sigma/authorize - Direct Bitcoin authentication

Profile Endpoints

GET /api/profile - Get user profile
POST /api/profile/create - Create user profile
PUT /api/profile - Update user profile

Discovery Endpoints

GET /.well-known/openid-configuration - OpenID Connect discovery
GET /.well-known/jwks.json - JSON Web Key Set

Backup Endpoints

GET /api/backup - Retrieve encrypted backup (by bapId or oauthId)
POST /api/backup - Store encrypted backup
POST /api/backup/link-oauth - Link OAuth account to BAP ID
GET /api/backup/status - Get backup status

Utility Endpoints

GET /health - Health check

Authentication Providers

Sigma Provider

Uses Bitcoin cryptographic signatures for passwordless authentication.

Google Provider

Standard Google OAuth 2.0 integration.

GitHub Provider

Standard GitHub OAuth 2.0 integration.

OAuth 2.0 Endpoints

Authorization Endpoint

GET /oauth2/authorize

Initiates the OAuth authorization flow. This is a custom gate that checks wallet access before forwarding to Better Auth's OAuth endpoint.

Parameters:

Parameter	Type	Required	Description
`client_id`	string	Yes	Your application identifier
`redirect_uri`	string	Yes	URL to redirect after authorization
`response_type`	string	Yes	Must be `code` for authorization code flow
`provider`	string	No	Provider: `sigma`, `google`, `github` (defaults to `sigma`)
`state`	string	No	CSRF protection parameter
`scope`	string	No	Requested scopes (space-separated)
`code_challenge`	string	No	PKCE code challenge (recommended)
`code_challenge_method`	string	No	Must be `S256` when using PKCE

Example:

https://auth.sigmaidentity.com/oauth2/authorize?
  client_id=your-app&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  provider=sigma

Token Endpoint

POST /api/auth/oauth2/token

Exchange authorization code for access token.

Content-Type: application/json

Request Body:

Field	Type	Required	Description
`grant_type`	string	Yes	Must be `authorization_code`
`code`	string	Yes	Authorization code from redirect
`client_id`	string	Yes	Your application identifier
`redirect_uri`	string	Yes	Must match original redirect_uri
`code_verifier`	string	No	PKCE code verifier (required if code_challenge was used)

Response:

{
  "access_token": "eyJhbGciOiJFUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 2592000
}

UserInfo Endpoint

GET /api/auth/oauth2/userinfo

Get authenticated user information. Returns standard OIDC claims plus custom pubkey and bap fields.

Headers:

Authorization: Bearer <access_token>

Response (with BAP profile):

{
  "sub": "user_abc123def456",
  "name": "johndoe",
  "given_name": "John",
  "family_name": "Doe",
  "picture": "https://ordfs.network/abc123_62",
  "pubkey": "02a94e09bcd6085e580f9214d2814e985f348b1b24121b2aff70a169f971ff5699",
  "bap": {
    "idKey": "GpWrvdYWq3DUWMcw8vF8cFYoBK7",
    "rootAddress": "1GXdTRDtQGKZ6yp2oUkDf8SuVhBf8Ww7ki",
    "currentAddress": "1PHiKmPMqUSi5AWDYHMT3CvQ9rFAFnax8j",
    "addresses": [
      {
        "address": "1PHiKmPMqUSi5AWDYHMT3CvQ9rFAFnax8j",
        "txId": "dcc70a6b3a...",
        "block": 864381
      }
    ],
    "identity": {
      "@type": "Person",
      "@context": "https://schema.org",
      "alternateName": "johndoe",
      "givenName": "John",
      "familyName": "Doe",
      "image": "https://ordfs.network/abc123_62",
      "description": "Bitcoin developer"
    },
    "firstSeen": 864381,
    "txHash": "dcc70a6b3a..."
  }
}

Response (without BAP profile):

{
  "sub": "user_abc123def456",
  "name": "1BitcoinAddress...",
  "pubkey": "02a94e09bcd6085e580f9214d2814e985f348b1b24121b2aff70a169f971ff5699",
  "bap": null
}

Discovery Endpoints

OpenID Configuration

GET /.well-known/openid-configuration

Returns OAuth 2.0/OIDC server metadata.

JWKS Endpoint

GET /.well-known/jwks.json

Returns public keys for JWT signature verification.

Profile Management Endpoints

See Profile API Documentation for details on profile endpoints.

Backup Service Endpoints

See Backup API Documentation for details on backup endpoints.

Rate Limiting

OAuth endpoints: 10 requests per minute per IP
API endpoints: 100 requests per minute per user
Failed authentication: Progressive delays after failed attempts

On this page