API Documentation

1. API Keys (Simplest)

Create an API key in the Developer Portal and include it in the Authorization header.

Authorization: Bearer psk_live_abc123def456...

API keys are scoped to your account and can be restricted to specific permissions. Use psk_test_ keys for sandbox testing.

2. OAuth 2.0 (For Apps)

Use OAuth 2.0 when building apps that act on behalf of PlotSparkOS users.

Authorization Code Flow

# 1. Redirect user to authorize
GET /api/v1/oauth/authorize?
  client_id=psc_abc123&
  redirect_uri=https://myapp.com/callback&
  scope=read:collections+write:collections&
  state=random_state

# 2. Exchange code for tokens
POST /api/v1/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "received_auth_code",
  "client_id": "psc_abc123",
  "client_secret": "pss_secret...",
  "redirect_uri": "https://myapp.com/callback"
}

# 3. Use access token
Authorization: Bearer eyJhbGc...

Client Credentials Flow (Server-to-Server)

POST /api/v1/oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "psc_abc123",
  "client_secret": "pss_secret...",
  "scope": "read:collections write:collections"
}