On this page
An API key is what authenticates a request to VGraple CRM's REST API v1 or the Zapier app connected to it, created from Settings > API Keys with the full secret shown exactly once. This walkthrough covers creating your first key, understanding the difference between rotating and revoking one, and what stops working when you do either.
API keys: first 5 of 7 steps
- 1Open Settings and go to API Keys
- 2Name the key and pick its access
- 3Click Create Key
- 4Copy the secret now
- 5Use it as a Bearer token
Before you start
- Creating, rotating or revoking API keys is restricted to the organisation owner, or the platform super admin. Admins, supervisors and custom roles cannot see this page even if they can manage other org settings.
- Decide what you are naming the key for before you create it, "Zapier," "Website backend," "Order sync script." A key cannot be renamed later, only rotated or revoked and replaced with a fresh one.
- Decide whether the integration needs to write. Anything that only pulls data out, a reporting dashboard, a data warehouse sync, an analytics job, should get a Read-only key. Access level is fixed at creation too.
- Have somewhere secure ready to paste the secret the moment it appears, a password manager or your integration's environment variables, since it is shown exactly once and cannot be retrieved again.
Steps
- Open Settings and go to API Keys. From the sidebar, click Settings, then API Keys. If you do not see this page, you are not the organisation owner; ask the owner to create the key for you or to add you as owner if that is genuinely your role.
Name the key and pick its access level. In the field at the top, type a name that identifies what will use it, up to 60 characters, for example "Zapier" or "Order sync script." This name is the only thing distinguishing one key from another in the list afterward. Next to it, choose Full access if the integration needs to send messages or create records, or Read-only if it only reads. Read-only keys are accepted on every GET endpoint and rejected with a 403 on anything that writes.
Click Create Key. The key is generated immediately:
vgk_followed by 48 hex characters. A green panel appears with the full secret and a Copy button.Copy the secret now. This is the only moment you will ever see the full value. Paste it straight into whatever needs it, your Zapier connection dialog, an environment variable, a script's config, rather than leaving it in a chat message or a text file longer than necessary.
Use it as a Bearer token. Every request to the REST API needs
Authorization: Bearer vgk_your_key_herein its headers. In Zapier, paste the same value into the API Key field when connecting the VGraple CRM app; the connection test callsGET /api/v1/meand shows your organisation's name if it worked.Rotate a key if it may have been exposed. Click the refresh icon next to a key in the list. This generates a new secret for the same key record, shown once just like at creation, and the old secret stops working the instant you rotate, so update every place that used the old value right away.
Revoke a key you no longer need. Click the trash icon, then confirm. This deletes the key permanently; anything still sending that key gets an authentication failure on its next call.
What you will see
The API Keys page lists every key your organisation has created, showing its name, an access badge reading Full access or Read-only, its prefix (the first 12 characters, enough to recognise which key is which without exposing the secret), when it was created, and when it was last used, or "never used" if nothing has called it yet. The full secret never appears in this list, only at the moment of creation or rotation.
Below the list is the full REST API v1 reference: every endpoint a key can call, grouped by resource, with the query parameters each one accepts.
Settings and options
| Setting or field | What it does | Default |
|---|---|---|
| Key name | Identifies the key in the list; not shown to whatever service uses the key | Required, up to 60 characters |
| Access level | Full access (read and write) or Read-only (403 on every write) | Full access; fixed at creation |
Secret (vgk_...) | The Bearer token sent on every API request | Shown once, hashed at rest afterward |
| Rotate | Replaces the secret on the same key record, same name, access level and history | Old secret stops working immediately |
| Revoke | Deletes the key entirely | Cannot be undone |
| Keys per organisation | Maximum number of active keys | 10 |
| Rate limit | Requests allowed per key per hour | 600, rolling window |
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Settings > API Keys is missing from the sidebar | Your role is not organisation owner and you are not a platform super admin | Ask the org owner to create the key, or to transfer ownership if you are meant to hold it |
| "Limit of 10 API keys reached" when creating a new one | Your organisation already has 10 active keys | Revoke a key you no longer use from the list, then create the new one |
| A Zap or script suddenly returns "Invalid API key" | The key was rotated or revoked, intentionally or by another team member with owner access | Check the key's status in Settings > API Keys; if it was rotated, update the integration with the new secret; if revoked, create a fresh key |
| "Rate limit exceeded (600 requests/hour)" | The integration using this key is making more than 600 calls an hour | Space out or batch requests; if you run multiple integrations, give each its own key so their limits do not compete |
A test call to GET /api/v1/me returns 401 | The key was typed with extra whitespace, missing the vgk_ prefix, or copied incorrectly | Recreate or rotate the key and copy the secret directly with the copy button rather than retyping it |
| A write call returns 403 "This API key is read-only" | The key was created with Read-only access | Create a full-access key for that integration; access level cannot be changed on an existing key |
| Deleted a key but a Zap is still technically "on" | Zapier's own hook subscription (in the webhook endpoint table) was not deleted when the key was revoked | Go to Settings > Webhooks, find the endpoint with the "Zapier" badge, and delete it there, or reconnect the Zap with a new key |
What's the difference between an API key and a webhook secret?
An API key authenticates requests you make to VGraple CRM, when your script or Zapier calls GET /api/v1/contacts or POST /api/v1/messages, that request needs your key in its Authorization header. A webhook secret does the opposite job: it lets your receiving server verify that a request VGraple CRM sent to you actually came from VGraple CRM, by recomputing an HMAC signature. One key authenticates you to us; one secret authenticates us to you. A single integration, like a Zapier connection, typically uses both: your API key to call the API, and a separate webhook secret (generated automatically when the Zap subscribes) to verify what comes back.
Watch out
Treat an API key exactly like a password. Anyone with a valid full-access key can read and write your organisation's contacts, leads, messages and broadcasts through the API. If a key ends up in a public script, a shared document or a client-side app, rotate it immediately rather than waiting for a scheduled cleanup. Giving read-only integrations a read-only key is what limits the damage of exactly that mistake.
Once you have a key, the REST API quickstart walks through your first calls, exporting your message history covers pulling every conversation into your own database, and connecting Zapier shows how the same key powers the no-code app.