# 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](https://app.plentylabs.com/create), 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:

```shell
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](https://app.plentylabs.com/api/schema.graphql) 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.