GraphQL APIAuthentication

Authentication

The PlentyLabs API is authenticated with workspace API keys. A key belongs to one workspace and never has more access than the person who created it.

API keys

Only a workspace owner can create a key.

  1. In PlentyLabs, open Settings, then Developers, then API keys.
  2. Name the key and choose its access: read and write, or read only.
  3. Optionally, choose an expiry: 30 days, 90 days or 1 year.
  4. Copy the key. It starts with plenty_sk_ and is shown once.

Never commit the key or send it to a browser.

Sending the key

Pass the key in the Authorization header as a bearer token on every request:

export PLENTY_API_KEY=plenty_sk_...

curl https://api.plentylabs.com/graphql \
  -H "Authorization: Bearer $PLENTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "query GetWorkspace { apiCredentialWorkspace { id name } }" }'

Workspace scope

A key works only in its own workspace. Any other workspace id is refused, even one the key's creator belongs to. Get the workspaceId every list query needs from apiCredentialWorkspace.

Access

A read-only key has the guest role: it can read the workspace, and anything more depends on its creator's access. A read and write key acts as its creator.

A key never has more access than its creator, and follows changes to the creator's role. It stops working when the creator leaves the workspace.

A key can use only what the published schema holds. Anything else returns FORBIDDEN. Account and key management are not available to keys.

Expiry and revocation

Revoke a key in Settings, Developers, API keys. Revocation takes effect on the next request. The key's usage history is kept, and the same page shows each key's credit usage.