Authentication

The TokPortal API uses API keys to authenticate requests. Include your key in the X-API-Key header on every request.

API Key Format

Keys follow the format:

tok_live_<32 hexadecimal characters>

Example:

tok_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Generating an API Key

1. Sign in to your TokPortal account.
2. Navigate to Developer > API Keys at app.tokportal.com/developer/api-keys.
3. Click Create New Key.
4. Copy the key immediately — it is shown only once.

You can create multiple keys per account. This is useful for separating keys across environments (development, staging, production) or across different services.

Key Storage and Security

API keys are hashed with SHA-256 before being stored. TokPortal never retains the plain-text version of your key. If you lose a key, you must revoke it and generate a new one.

Making Authenticated Requests

Pass your API key in the X-API-Key header:

curl -X GET https://app.tokportal.com/api/ext/me \
  -H "X-API-Key: tok_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

Success response:

{
  "data": {
    "email": "you@example.com",
    "credits": 1250
  }
}

Invalid or missing key:

{
  "error": {
    "code": "AUTH_INVALID_KEY",
    "message": "The provided API key is invalid."
  }
}

Error Codes

Code	HTTP Status	Description
AUTH_MISSING_KEY	401	No X-API-Key header was provided.
AUTH_INVALID_KEY	401	The key does not match any account.
AUTH_REVOKED_KEY	401	The key has been revoked. Generate a new one.

Security Best Practices

• Use environment variables. Never hard-code API keys in source code.

  export TOKPORTAL_API_KEY="tok_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

  curl -X GET https://app.tokportal.com/api/ext/me \
    -H "X-API-Key: $TOKPORTAL_API_KEY"

• Never expose keys client-side. API keys must only be used in server-side code. Never include them in frontend JavaScript, mobile apps, or public repositories.

• Rotate keys regularly. Create a new key, migrate your services, then revoke the old one.

• Use separate keys per environment. Keep production and development keys distinct so revoking one does not affect the other.

• Revoke compromised keys immediately. If a key is exposed, revoke it from the developer dashboard and generate a replacement.