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.

ScopeAllows
workspace:readGET /me, GET /webhook-events
senders:readGET /accounts, GET /accounts/{id}
leads:readGET /leads, GET /leads/{id}, GET /lists
leads:writePOST /leads, POST /lists, POST /lists/{id}/leads
campaigns:readGET /campaigns, GET /campaigns/{id}, GET /campaigns/{id}/stats
campaigns:writePOST /campaigns/{id}/leads, POST /campaigns/{id}/pause, POST /campaigns/{id}/resume
inbox:readGET /conversations, GET /conversations/{id}/messages
inbox:writePOST /conversations/{id}/messages
webhooks:manageGET /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

StatusCodeMeaning
401invalid_api_keyThe key is missing, malformed, unknown or revoked.
403insufficient_scopeThe key is valid but lacks the scope for this endpoint.

See Conventions for the error format.

On this page