Create a new API key for an account

post

https://api.convert.com/api/v2/accounts/{account_id}/api-keys/add

Generates a new API key and secret for the specified account.
The key can be named for easier identification and can be restricted to a list of project IDs.
If no projects are specified, the key grants access to all projects in the account.
The API secret is only shown at the time of creation and should be stored securely.

A key scoped to all projects (projects omitted or null) requires the caller to be an owner, account manager or admin holding all-projects access. The key's role may be no stronger than the caller's account role.
A key scoped to specific projects is available to project-scoped users, and its role may be no stronger than the caller's role on each of the requested projects.
When role is omitted it defaults to the weakest role the caller holds across the requested projects, or to their account role for an all-projects key; owner is downgraded to account_manager.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

account_id

integer

required

ID of the account that owns the retrieved/saved data

Body Params

Contains the name for the new API key for easy identification, and an optional list of projects (by ID) to which this key will grant access. If projects is omitted, the key typically grants access to all projects in the account.

Defines an API key used for authenticating server-side requests to the Convert API.

name

string

required

length between 2 and 100

A user-defined, friendly name for the API key to help identify its purpose or the application using it (e.g., "Reporting Dashboard Integration", "Nightly Data Sync Script").

auth_type

string

enum

Defaults to requestSigning

The authentication type for this API key:

requestSigning: Each request must be signed with the key and a hash sent in the header (most secure)
secretKey: A simpler authentication method using the secret key as a Bearer token in the Authorization header (good security)

Allowed:

projects

array of numbers | null

An optional list of project IDs that this API key is authorized to access.
If null or an empty list, the key typically grants access to all projects within the account it belongs to.
This allows for granular control over API key permissions.

projects

role

string

enum

The role assigned to this API key, which determines its permissions.
For a key scoped to specific projects it must be no stronger than the creator's role on each of those projects; for a key scoped to all projects it must be no stronger than the creator's account role.
If not specified, it defaults to the weakest role the creator holds across the requested projects, or to their account role for an all-projects key. For legacy keys, a default role of account_manager is returned.

Allowed:

Responses

Language

Credentials

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

201Details of a single API key, including its name, ID, associated projects, and the API secret (only shown in full upon creation).

defaultIndicates an error occurred while processing the request. The code provides an HTTP status code, message offers a human-readable explanation or an array of validation errors, and fields (if present) specifies which input fields were problematic.