DocsBlog
API Keys
On this page

API Key

An API Key in the Paylias network represents a long-lived access token with fine-grained permissions. These keys are linked to specific Domains and enable secure access to Paylias's networked APIs.

Overview

Each API Key:

  • Links to a specific Domain
  • Contains customizable access permissions
  • Can be rotated for security
  • Supports enable/disable functionality

API Resource

Property Type Description Notes
token string Unique identifier for the API key Auto-generated upon creation
partner_id string Associated Domain ID Links to Domain record
name string Display name for the API key Required
description string Purpose or usage notes Optional
secret_key string The actual API key value Used for authentication
enabled boolean Active status of the key Can be toggled
access object Permission configuration See Access Properties
created_at timestamp Creation timestamp Unix timestamp in seconds
updated_at timestamp Last update timestamp Unix timestamp in seconds

Access Properties

Property Type Description
customers_read boolean Permission to read customer data
customers_write boolean Permission to modify customer data
transactions_read boolean Permission to read transaction data
transactions_write boolean Permission to modify transaction data

Authentication

All API Key management operations require:

  • JWT token in the Authorization header
  • Domain token in the X-Partner-ID header

API Endpoints

Create API Key

Creates a new API key with specified permissions.

Required Parameters

Parameter Type Required Description
name string Yes Display name for the key
description string No Usage description
enabled boolean No Initial status
access object Yes Permission configuration

POST /api/v1/csp/apikey

curl --location 'https://production.oysterapi.net/csp/api/v1/csp/apikey' \
--header 'X-Partner-ID: part_ct23b6420or249k5boag' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <jwt_token>' \
--data '{
    "name": "Developer Api Key",
    "description": "Api key for developers",
    "enabled": true,
    "access": {
        "customers_read": true,
        "customers_write": true,
        "transactions_read": true,
        "transactions_write": true
    }
}'

Example Response

{
    "ok": true,
    "data": {
        "token": "api_cjbkn2nsemvqdjehm1eg",
        "partner_id": "part_31c2fa0e-d61b-447d-8acc-0d5d5df86b67",
        "name": "Developer Api Key",
        "description": "Api key for developers",
        "secret_key": "65B64EAE79E1112B76D403DA9344C278",
        "enabled": true,
        "access": {
            "customers_read": true,
            "customers_write": true,
            "transactions_read": true,
            "transactions_write": true
        },
        "created_at": {
            "seconds": 1691831179
        },
        "updated_at": {
            "seconds": 1691831179
        }
    }
}

Update API Key

Updates an existing API key's properties and permissions.

Path Parameters

Parameter Type Required Description
apiKey string Yes API key to update

Required Parameters

Parameter Type Required Description
name string Yes New display name
description string No Updated description
enabled boolean No Updated status
access object Yes Updated permissions

PUT /api/v1/csp/apikey/{apiKey}

curl --location --request PUT 'https://production.oysterapi.net/csp/api/v1/csp/apikey/AB6DBC62DBA42EE52BC3928E772FBE3C' \
--header 'X-Partner-ID: part_cjes76vsemvj3obsnc30' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <jwt_token>' \
--data '{
    "name": "Customers Api Key (Enabled)",
    "description": "Api key for customer API access",
    "enabled": true,
    "access": {
        "customers_read": true,
        "customers_write": true,
        "transactions_read": true,
        "transactions_write": true
    }
}'

Example Response

{
    "ok": true,
    "data": {
        "token": "api_cjetgi7semvjct8hhqm0",
        "partner_id": "part_cjes76vsemvj3obsnc30",
        "name": "Customers Api Key (Enabled)",
        "description": "Api key for customer API access",
        "secret_key": "AB6DBC62DBA42EE52BC3928E772FBE3C",
        "enabled": true,
        "access": {
            "customers_read": true,
            "customers_write": true,
            "transactions_read": true,
            "transactions_write": true
        },
        "created_at": {
            "seconds": 1692260424
        },
        "updated_at": {
            "seconds": 1692260453
        }
    }
}

Find API Key

Retrieves details of a specific API key.

Path Parameters

Parameter Type Required Description
apiKey string Yes API key to retrieve

GET /api/v1/csp/apikey/{apiKey}

curl --location 'https://production.oysterapi.net/csp/api/v1/csp/apikey/AB6DBC62DBA42EE52BC3928E772FBE3C' \
--header 'X-Partner-ID: part_cjes76vsemvj3obsnc30' \
--header 'Authorization: Bearer <jwt_token>'

Example Response

{
    "ok": true,
    "data": {
        "token": "api_cjetgi7semvjct8hhqm0",
        "partner_id": "part_cjes76vsemvj3obsnc30",
        "name": "Customers Api Key (Enabled)",
        "description": "Api key for customer API access",
        "secret_key": "AB6DBC62DBA42EE52BC3928E772FBE3C",
        "enabled": true,
        "access": {
            "customers_read": true,
            "customers_write": true,
            "transactions_read": true,
            "transactions_write": true
        },
        "created_at": {
            "seconds": 1692260424
        },
        "updated_at": {
            "seconds": 1692260453
        }
    }
}

Rotate API Key

Generates a new secret for an existing API key. Previous secret becomes invalid.

Path Parameters

Parameter Type Required Description
apiKey string Yes API key to rotate

POST /api/v1/csp/apikey/{apiKey}

curl --location --request POST 'https://production.oysterapi.net/csp/api/v1/csp/apikey/AB6DBC62DBA42EE52BC3928E772FBE3C' \
--header 'X-Partner-ID: part_cjes76vsemvj3obsnc30' \
--header 'Authorization: Bearer <jwt_token>'

Example Response

{
    "ok": true,
    "data": {
        "token": "api_cjetgi7semvjct8hhqm0",
        "partner_id": "part_cjes76vsemvj3obsnc30",
        "name": "Customers Api Key (Enabled)",
        "description": "Api key for customer API access",
        "secret_key": "36BFB7C90C7A1D3D4E09E2E2C05DDD3E",
        "enabled": true,
        "access": {
            "customers_read": true,
            "customers_write": true,
            "transactions_read": true,
            "transactions_write": true
        },
        "created_at": {
            "seconds": 1692260424
        },
        "updated_at": {
            "seconds": 1692270721
        }
    }
}

List API Keys

Retrieves a paginated list of API keys with optional filters.

Query Parameters

Parameter Type Required Description
names string[] No Filter by key names
api_keys string[] No Filter by specific keys
enabled boolean Yes Filter by status
limit integer Yes Results per page
page integer Yes Page number

GET /api/v1/csp/apikey

curl --location 'https://production.oysterapi.net/csp/api/v1/csp/apikey?names=Customers&api_keys=36BFB7C90C7A1D3D4E09E2E2C05DDD3E&enabled=true&limit=3&page=1' \
--header 'X-Partner-ID: part_cjes76vsemvj3obsnc30' \
--header 'Authorization: Bearer <jwt_token>'

Example Response

{
    "ok": true,
    "data": {
        "count": 1,
        "api_keys": [
            {
                "token": "api_cjetgi7semvjct8hhqm0",
                "partner_id": "part_cjes76vsemvj3obsnc30",
                "name": "Customers Api Key (Enabled)",
                "description": "Api key for customer API access",
                "secret_key": "36BFB7C90C7A1D3D4E09E2E2C05DDD3E",
                "enabled": true,
                "access": {
                    "customers_read": true,
                    "customers_write": true,
                    "transactions_read": true,
                    "transactions_write": true
                },
                "created_at": {
                    "seconds": 1692260424
                },
                "updated_at": {
                    "seconds": 1692270721
                }
            }
        ]
    }
}

Common Error Codes

Error Code Description
error.bad_request Invalid or missing required parameters
error.resource_not_found API key not found
error.unauthorized_access Invalid or missing authentication
500, 502, 503, 504 Server-side errors

Best Practices

  1. Key Management

    • Rotate keys periodically
    • Use descriptive names and descriptions
    • Limit permissions to only what's needed
    • Disable unused keys promptly

  2. Security

    • Never expose API keys in client-side code
    • Store keys securely
    • Use separate keys for different environments
    • Monitor key usage regularly
Docs and examples licensed under MIT