API Keys

API keys authenticate requests between servers and the Martis API. Each key is a unique credential that identifies the requesting application and determines access permissions. Proper key management is essential for maintaining security and preventing unauthorized access.

Overview

An API key consists of a secret string that must be included in the Authorization header of every API request. Keys are environment-specific — sandbox keys only work with the sandbox API, and production keys only work with the production API.

Component	Description
API Key	Secret credential generated by Martis
Environment	Sandbox or production scope
Permissions	Access level granted to the key

API keys provide full access to the account. Never expose keys in client-side code, public repositories, or logs.

Generate an API Key

Only account owners or authorized team members can create API keys.

Steps

Sign in to the Creator Hub
Navigate to Integration → API Keys
Click Create new API key and enter a descriptive name
Copy the secret key immediately — it is displayed only once

Key Storage

Store API keys securely using one of the following methods:

Method	Description
Environment Variables	Store keys in server environment variables
Secrets Manager	Use a dedicated secrets management service (e.g., AWS Secrets Manager, HashiCorp Vault)
Encrypted Configuration	Store in encrypted configuration files with restricted access

Security Requirements

Never commit keys to version control
Never include keys in client-side code
Rotate keys periodically and immediately upon suspected compromise
Use separate keys for each service or application
Remove unused keys promptly

IP Restrictions

Restrict API key usage to specific IP addresses for enhanced security. When enabled, requests from non-listed IP addresses are rejected.

Configuration	Allowed IPs	Best For
Unrestricted	Any IP address	Development, internal testing
Restricted	Listed IPs only	Production, locked-down environments

Configure IP Restrictions

Navigate to Integration → API Keys
Select the key to configure
Click Manage IP Restrictions
Add allowed IP addresses or CIDR ranges
Save changes

IP restrictions add a security layer but do not replace proper key management. A leaked key from an allowed IP still poses a risk.

Key Rotation

Regular key rotation limits the impact of potential key exposure.

Rotation Process

Generate a new API key
Update the application to use the new key
Verify the application functions correctly
Revoke the old key

Rotation Triggers

Scheduled rotation (recommended: every 90 days)
Team member departure
Suspected key compromise
Security audit findings

Revoke a Key

Revoked keys immediately stop working. This action cannot be undone.

Navigate to Integration → API Keys
Locate the key to revoke
Click the options menu (⋮)
Select Revoke
Confirm the revocation

Before revoking a key, ensure no active services depend on it. Revocation causes immediate authentication failures for any requests using that key.

Using API Keys

Include the API key in the Authorization header using the Bearer scheme:

Request with API key

curl https://api-staging.martis.id/api/v1/payments/charges \
  --header 'Authorization: Bearer {API_KEY}' \
  --header 'Content-Type: application/json'

Header Format

Authorization: Bearer sk_live_abc123xyz...

Error Responses

Status	Description
`401 Unauthorized`	Invalid, expired, or missing API key
`403 Forbidden`	Valid key but insufficient permissions for the requested action

Environment-Specific Keys

Each environment requires its own API key:

Environment	Key Prefix	Base URL
Sandbox	`sk_test_`	`https://api-staging.martis.id`
Production	`sk_live_`	`https://api.martis.id`

Using a sandbox key with the production API (or vice versa) returns a 401 Unauthorized error.

Best Practices

Descriptive naming — Name keys by purpose (e.g., "Backend Production", "Webhook Service")
Minimal access — Grant only the permissions each service requires
Separate keys — Use different keys for different services or environments
Audit regularly — Review active keys and remove those no longer in use
Monitor usage — Track API key usage patterns to detect anomalies

Authentication Guide