Authentication

The Flintn API uses API keys to authenticate requests. Each API key is scoped to a specific merchant and can be configured with granular permissions.

API Keys

You can create and manage your API keys at hub.flintn.com/developers.

Key Format

API keys follow a specific format based on the environment:

Environment	Format	Example
Production	pk_live_*	pk_live_abc123def456...
Sandbox	pk_test_*	pk_test_xyz789ghi012...

Important: The full API key is displayed only once when created. Store it securely immediately, as you will not be able to retrieve it again. You will only see the last four characters of the key in the dashboard afterward.

Security Best Practices

• Do not share your API keys in publicly accessible areas

• Do not commit API keys to version control

• Use environment variables to store keys

• Use the minimum permissions required for your integration

• Rotate keys periodically and after any suspected compromise

API Key Permissions

When creating an API key, you must specify which permissions it should have. This follows the principle of least privilege—only grant the permissions your integration actually needs.

Permission	Description
transaction.read	Read transaction data
transaction.search	Search transactions
transaction.refund	Refund transactions
transaction.void	Void transactions
transaction.capture	Capture authorized transactions
client_session.create	Create client sessions for payments
subscription.read	Read subscription data
subscription.search	Search subscriptions
subscription.client_session.create	Create client sessions for subscriptions
subscription_plan.read	Read subscription plans
subscription_plan.write	Create and modify subscription plans

Managing API Keys

API keys have three possible statuses:

Status	Description
Active	Key can be used for API requests
Disabled	Key is temporarily inactive but can be reactivated
Revoked	Key is permanently disabled and cannot be reactivated

Creating an API Key

1. Go to hub.flintn.com/developers

2. Navigate to API Keys

3. Click Create API Key

4. Enter a descriptive name (e.g., "Production Backend", "Mobile App")

5. Select the required permissions

6. Click Create

7. Copy and securely store the API key immediately

Disabling and Reactivating Keys

You can temporarily disable an API key if you need to pause an integration. Disabled keys can be reactivated at any time.

Revoking Keys

If an API key is compromised or no longer needed, revoke it immediately. Revocation is permanent—revoked keys cannot be reactivated. You will need to create a new key.

Making Authenticated Requests

Include your API key in the X-Api-Key header:

curl -X GET https://api.flintn.com/v1/transactions \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Environments

Environment	Base URL	API Key Prefix
Production	https://api.flintn.com/v1	pk_live_*
Sandbox	https://sandbox.api.flintn.com/v1	pk_test_*

Use sandbox keys for development and testing. Sandbox transactions do not process real payments.

Error Responses

401 Unauthorized

Returned when the API key is invalid, missing, or revoked:

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "path": "/v1/transactions",
  "message": "Invalid API key provided",
  "code": "UNAUTHORIZED",
  "timestamp": "2024-01-15T10:30:00.123456Z"
}

403 Forbidden

Returned when the API key is valid but lacks the required permission for the requested operation:

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "path": "/v1/transactions",
  "message": "Insufficient permissions for this operation",
  "code": "FORBIDDEN",
  "timestamp": "2024-01-15T10:30:00.123456Z"
}

To resolve a 403 error, either use a different API key with the required permissions, or update the existing key's permissions in the dashboard.

The request_id field can be used when contacting support to help diagnose issues.