Authentication

Authenticating against the Convoy API requires a Bearer token. Convoy supports two API key types for different scopes.

Project API key

A project API key is scoped to one project. Use it for everything under /api/v1/projects/{projectID}/... (endpoints, events, subscriptions, sources, and so on). You get a project API key:

In the create-project response (api_key), shown once
From the project settings dashboard (regenerate)

terminal

curl {base_url}/api/v1/projects/{projectID}/{resource} \
  -H "Authorization: Bearer PROJECT_API_KEY" \
  -H "Content-Type: application/json" \
  -X GET

Personal API key

A personal API key is scoped to a user and their organisation membership. Use it for organisation-scoped project operations such as create a project and list projects. Pass the organisation id as the orgID query parameter. On self-hosted, convoy bootstrap --with-api-key can mint and print a personal API key (see CLI bootstrap). You can also create personal keys from the dashboard security settings after login.

terminal

curl "{base_url}/api/v1/projects?orgID={organisationID}" \
  -H "Authorization: Bearer PERSONAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "staging", "type": "outgoing" }' \
  -X POST

Security

Your API keys are sensitive information. Do not share them in publicly accessible areas such as GitHub, client-side code, and so forth. If a key is compromised, regenerate or revoke it.

Welcome Errors

​Project API key

​Personal API key

​Security

Project API key

Personal API key

Security