Authentication
Create gk_live_ API keys, choose scopes, and understand what a key can and cannot see.
Every request carries an API key as a bearer token:
curl -s https://app.graphkit.com/api/v1/me \
-H "Authorization: Bearer gk_live_..."Create a key
Open Settings → API keys in the workspace and choose Create API key. Give it a name that says where it is used ("HubSpot sync"), pick the scopes, and copy the key. You need a role that can manage API keys (client admin or an agency role).
- The key starts with
gk_live_and is shown once. GraphKit stores only a hash and the short prefix you see in the list. - Revoke a key in the same place. It stops working on the next request.
- Store keys in a secret manager or environment variable, never in client-side code or a repository.
Scopes
A key can only call endpoints its scopes cover. Give each integration only what it needs.
| Scope | Allows |
|---|---|
workspace:read | GET /me, GET /webhook-events |
senders:read | GET /accounts, GET /accounts/{id} |
leads:read | GET /leads, GET /leads/{id}, GET /lists |
leads:write | POST /leads, POST /lists, POST /lists/{id}/leads |
campaigns:read | GET /campaigns, GET /campaigns/{id}, GET /campaigns/{id}/stats |
campaigns:write | POST /campaigns/{id}/leads, POST /campaigns/{id}/pause, POST /campaigns/{id}/resume |
inbox:read | GET /conversations, GET /conversations/{id}/messages |
inbox:write | POST /conversations/{id}/messages |
webhooks:manage | GET /webhooks, POST /webhooks, DELETE /webhooks/{id} |
senders:write can be chosen but no v1 endpoint uses it yet.
What a key can see
- One workspace. A key belongs to the workspace it was created in. An id from any other workspace returns
404 not_found, exactly like an id that does not exist. - No private conversations. Conversations on accounts marked private are never visible to API keys, whatever the scopes.
- Acts as its creator. Replies sent with a key are attributed to the person who created it. If that person is removed, create a new key.
- Audited. Every change made with a key is written to the workspace audit log, recorded as made by that key.
Errors
| Status | Code | Meaning |
|---|---|---|
| 401 | invalid_api_key | The key is missing, malformed, unknown or revoked. |
| 403 | insufficient_scope | The key is valid but lacks the scope for this endpoint. |
See Conventions for the error format.