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:

sk_<64 lowercase hexadecimal characters>

Example:

sk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

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.

Environments, Scopes, and Expiry

When you create a key, tag it with an environment:

Environment	Recommended use
production	Live servers and partner integrations
staging	Pre-production validation
development	Local development
test	Short-lived experiments and CI smoke tests

Keys also support broad access scopes:

Scope	Allows
*	Full access. This is the default for existing keys.
read	GET requests only.
write	Mutating requests: POST, PUT, PATCH, and DELETE.

Use read-only keys for dashboards and sync jobs that never mutate TokPortal state. Use expiring keys for contractors, temporary scripts, and tests.

You can update a key's display name, environment tag, access scope, and expiry date from Developer > API Keys without rotating the secret. Rotate when the secret itself may be exposed or when you need a fresh value for deployment.

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.

Request IDs and Usage Logs

Every public API response includes X-TokPortal-Request-ID. Store this value in your logs and include it when contacting support.

TokPortal also records request usage per API key in the Developer Portal. Open Developer > API Keys, choose a key, and inspect recent requests, status codes, latency, credits charged, and request IDs. This makes it easier to debug one integration without mixing production, staging, and local traffic.

API Key Audit Trail

TokPortal records key lifecycle events separately from request logs:

• key created
• key metadata updated
• key rotated
• rotation replacement key created
• key revoked

Open Developer > API Keys, choose a key, and inspect Key audit trail to see when the key changed and which metadata was attached at the time, including environment, scopes, expiry, and rotation links.

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: sk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

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.
AUTH_EXPIRED_KEY	401	The key has expired. Generate or rotate to a new key.
AUTH_FORBIDDEN_SCOPE	403	The key does not include the required read or write scope.

Security Best Practices

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

  export TOKPORTAL_API_KEY="sk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
  

  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.

• Use narrow scopes. Prefer read-only keys for analytics/reporting jobs and full-access keys only for services that create or update resources.

• Set expiry dates for temporary access. Expiring keys are useful for tests, agencies, contractors, and short-lived scripts.

• Review the audit trail. Check key lifecycle events during incident response or before deleting old integrations.

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