Authentication

The Blackwalnut API uses Bearer token authentication. Create API keys from your dashboard and include them in request headers.

API Key Types

sk_* Secret

Secret Keys

Full read and write access to all resources. Use for server-side integrations only.

  • Create, update, and delete apps, customers, licenses
  • Generate and revoke license tokens
  • Rotate RSA keys

Security: Never expose secret keys in client-side code, public repositories, or browser requests.

pk_* Public

Public Keys

Read-only access. Safe for use in client applications where needed.

  • List apps, tiers, features
  • Read customer and license information
  • Cannot create, update, or delete resources

Using API Keys

Include your API key in the Authorization header:

HTTP Header 
Authorization: Bearer sk_live_your_api_key_here

cURL Example

terminal 
$ curl https://your-instance.com/api/v1/apps \
  -H "Authorization: Bearer sk_live_abc123xyz"

Managing API Keys

Create and manage API keys from your Blackwalnut dashboard under Settings > API Keys.

Best Practices

  • Create separate keys for different integrations
  • Rotate keys periodically
  • Use environment variables to store keys
  • Monitor key usage in the dashboard
  • Revoke unused or compromised keys immediately

Error Responses

401 Unauthorized

Returned when the API key is missing or invalid:

Response 
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

403 Forbidden

Returned when using a public key (pk_*) for write operations:

Response 
{
  "error": {
    "code": "forbidden",
    "message": "Write access requires a secret key (sk_*)"
  }
}

Public Endpoints

Some endpoints don't require authentication:

  • GET /api/v1/apps/:slug/public-key - Get app's public RSA key
  • GET /api/v1/apps/:slug/licenses/verify - Verify license status
  • POST /api/v1/apps/:slug/licenses/verify/batch - Batch verify
  • GET /api/health - Health check
API Overview Apps API