Token Verification

Verify JWT tokens returned by the AuthGate proxy to authenticate users in your application.

POST/api/v1/token/verify

Verify a token

Verifies a JWT token and returns the decoded user information. The token must not be expired and must have been signed by your project's secret.

Authentication

Include your API key in the Authorization header:

Authorization: Bearer your_api_key_here

Request body

Name
token
Type
string
Description
The JWT token received from the AuthGate callback.

Response

Name
valid
Type
boolean
Description
Whether the token is valid and not expired.
Name
user
Type
object
Description
The decoded user information from the token.
Name
user.id
Type
string
Description
The AuthGate end user ID.
Name
user.email
Type
string | null
Description
The user's email address.
Name
user.name
Type
string | null
Description
The user's display name.
Name
user.picture
Type
string | null
Description
URL to the user's avatar.
Name
user.provider
Type
string
Description
The OAuth provider used (e.g., github, google).
Name
expiresAt
Type
string
Description
ISO 8601 timestamp when the token expires.
Name
mfa
Type
object
Description
MFA enrollment status for the user (included when applicable).
Name
mfa.enrolled
Type
boolean
Description
Whether the user has any MFA method enabled.
Name
mfa.methods
Type
string[]
Description
List of enrolled MFA methods (e.g., ["totp"], ["totp", "sms"]).

Example request

curl -X POST https://auth.example.com/api/v1/token/verify \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"token": "eyJhbGciOiJIUzI1NiIs..."}'

Example response

{
  "valid": true,
  "user": {
    "id": "user_abc123",
    "email": "jane@example.com",
    "name": "Jane Doe",
    "picture": "https://avatars.githubusercontent.com/u/12345",
    "provider": "github"
  },
  "mfa": {
    "enrolled": true,
    "methods": ["totp"]
  },
  "expiresAt": "2025-01-15T10:05:00.000Z"
}

Token details

Algorithm: HS256
Expiry: 5 minutes from issuance
Issuer: authgate
Audience: session — all session JWTs carry aud: "session". Link tokens use aud: "link" and cannot be verified through this endpoint.

Tokens are intentionally short-lived. Verify the token immediately when you receive it at your callback URL and create your own session. Do not use the AuthGate token as a long-lived session token.

Error responses

Status	Description
`401`	Missing or invalid API key
`400`	Missing `token` in request body
`401`	Token invalid or expired — returns `{ "valid": false, "error": "Invalid or expired token" }`