API Keys

Picklayer uses two types of API keys for different purposes:

Key type	Prefix	Purpose	Auth flow
Publishable key	`pk_*`	End-User API — embed in client apps to mint ephemeral tokens	`MintEphemeral` action
Secret key	`sk_live_*`	Management API — programmatic org management for agents/scripts	`ExchangeSecretKey` mutation

Secret Keys (Management API)

Secret keys let AI agents and automation scripts manage your Picklayer organization without interactive sign-in. They provide the same access as the Builder UI.

Creating a secret key

Create keys in the Builder UI (Keys page) or via GraphQL:


mutation {
  insert_application_keys_one(object: {
    application_id: "<appId>"
    name: "My Agent Key"
    prefix: "sk_live"
    hashed_secret: "<sha256 hash of the key>"
    last4: "<last 4 chars>"
    scopes: ["read", "manage"]
  }) {
    id name prefix last4 scopes created_at
  }
}

Exchanging a key for an organization token


mutation {
  ExchangeSecretKey(secretKey: "sk_live_abc123...") {
    code message type
    data {
      organizationToken   # Use as Bearer token
      organizationId
      organizationName
      scopes
      expiresIn           # 3600 (1 hour)
    }
  }
}

Call this against https://api.picklayer.ai/v1/graphql with x-hasura-role: public (no auth needed).

Using the token


# All subsequent GraphQL calls use the org token
curl https://api.picklayer.ai/v1/graphql \
  -H "Authorization: Bearer <organizationToken>" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ applications { id name } }"}'
 
# For app-scoped queries, add the app ID header
curl https://api.picklayer.ai/v1/graphql \
  -H "Authorization: Bearer <organizationToken>" \
  -H "x-hasura-application-id: <appId>" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ providers { id name type enabled } }"}'

Scopes

Scope	Access level
`read`	GraphQL queries — list and retrieve resources
`manage`	Queries + mutations — create and update resources
`admin`	Full access — includes destructive operations and key management

In v1, scopes are informational — the JWT grants full _builder role access. Use scopes to communicate intent.

Revoking a key


mutation {
  update_application_keys_by_pk(
    pk_columns: { id: "<keyId>" }
    _set: { revoked_at: "now()" }
  ) {
    id revoked_at
  }
}

Security best practices

Rotate keys periodically — set expires_at when creating keys
Use minimum scope — create read-only keys when write access isn’t needed
Never commit keys to source control — use environment variables
Revoke compromised keys immediately — revoked keys fail authentication instantly
One key per agent — easier to audit and revoke

Publishable Keys (End-User API)

Publishable keys (pk_*) are designed for client-side use. They mint short-lived ephemeral tokens (5 minutes) with capability constraints.

See the Authentication page for the full end-user auth flow.