API Settings

Open Settings → API Keys to manage REST and MCP access for the selected company. Viewing requires API settings access; creating, editing, rotating, and revoking keys also require permission to update API settings.

Each key belongs to its creator and one company. The page lists your keys for the selected company, plus your older keys that still need a company assignment. Use the REST guide for HTTP requests or the MCP guide for client connections.

Create a scoped key

1. Select Create API key and enter a descriptive name, such as CRM integration.
2. Optionally choose an expiry date and time in the timezone shown beside the field.
3. Assign permissions in the scope matrix. Select all selects the available BREAD permissions in that scope. A partial selection shows an indeterminate checkbox.
4. Select Save API key and copy the secret immediately. It is shown once.

The optional expiry must be in the future. Leaving it blank creates a key with no expiry. The key list shows a prefix for identification; it cannot reveal the complete secret later. Rotate an active key if you no longer have its secret.

New keys start with no permissions. You can only assign operations within your own current account access and subscription. A key's company is fixed; create a separate key for another company. The API checks company membership, current owner permissions, and the integration API subscription entitlement on each request. Integration API access uses the same active Scale, Pro, or contracted Enterprise requirement as the existing integration APIs. An Edit grant does not imply Read access: write responses include only the changed fields and resource identifiers.

Choose and review permissions

Use the scope search to find a resource. Select individual BREAD checkboxes or Select all for that row. Select all applies only to that scope and only to operations you can assign. Disabled checkboxes are outside your current access; a dash marks an unsupported operation. New operations added to the API later require an explicit grant.

The key list shows available / assigned. Assigned counts saved grants; available counts those still usable under the key's status and your current access. For example, 2 available / 3 assigned means one saved grant is currently unavailable. Expand View permissions to inspect the saved assignments. Exports and live MCP discovery use the available operations.

Select Edit to change a key's name, future expiry, or permissions, then Save API key. Permission changes apply to subsequent requests without rotating the secret. The editor offers only currently assignable permissions, so review the matrix before saving. Re-export definitions or refresh MCP discovery after changing grants.

Supported resource scopes

Unsupported actions show a dash. API grants apply to the supported fields in each schema; credentials, internal execution state, and arbitrary model fields are excluded.

See Account API Scopes and Fields for the full operation matrix, writable fields, required Add fields, and validation rules.

Export definitions for a key

Each key has Export Postman and Export MCP schemas actions. Exports include only the operations currently available to that key, after checking both its assignments and its owner's current access. They contain no credentials. Re-export after permissions change.

Import the Postman JSON collection into Postman, then set its api_key collection variable locally. base_url points to the API server; resource_id is a placeholder for operations on an existing resource. Requests include example payloads.

The MCP JSON contains the remote endpoint, authentication instructions, and the permitted tools' input schemas and annotations. It is a definition snapshot; live discovery from the endpoint reflects current permissions.

See API Definition Exports for import instructions, variable setup, REST download commands, and how permission changes affect an existing export.

Use the REST API

Send Authorization: Bearer <API_KEY> to the account-management API. The company comes from the credential; an X-Company-ID header cannot switch it to another company.

Add and Edit requests use a JSON body of resource attributes, for example:

{"name": "Customers", "description": "CRM customer list"}

Resource IDs are positive integers. Browse supports search, page, and per_page (maximum 100), and returns data plus pagination meta. Read and write responses return data. Unknown attributes and references to resources outside the key's company are rejected. Resource limits and existing model business rules still apply.

Authenticated definition endpoints are available at:

• GET /api/v1/account/capabilities
• GET /api/v1/account/exports/postman
• GET /api/v1/account/exports/mcp

The rate limit is 60 requests per minute per key, shared across REST and MCP. Subscription request allowances and tenant-wide API rate limits also apply. Invalid credentials return 401, denied permissions return 403, unavailable resources return 404, invalid inputs return 422, and rate-limited requests return 429 with Retry-After.

The REST guide includes a complete create/read/edit/delete example, Browse pagination, response shapes, and error handling.

Connect an MCP client

Use the MCP endpoint displayed on the API settings page, normally https://api.nviti.ng/api/v1/account/mcp, with Streamable HTTP and an Authorization: Bearer <API_KEY> header.

Tools use names such as browse_contact_groups, read_contact_groups, and edit_contact_groups. Add and Edit tool arguments contain an attributes object; Read, Edit, and Delete include an id. Tool discovery lists only permitted operations, and every execution rechecks access. This initial connection requires a client that supports custom Bearer headers; OAuth account connection is not yet provided. Browser clients must use an allowed Origin; administrators can add origins through ACCOUNT_MCP_ALLOWED_ORIGINS and override the exported server address through ACCOUNT_API_BASE_URL.

The MCP guide covers initialization, discovery cursors, tool calls, and MCP errors. Clients must follow nextCursor to discover all tools.

Rotate or revoke

Rotate replaces the secret and immediately invalidates its previous value and exchanged tokens. Copy the replacement once and update the integration. Revoke immediately disables the key and its exchanged tokens. API and settings mutations are recorded in an audit log without request contents or credentials.

Last used records authenticated account API use or token exchange. It does not mean that the requested resource operation succeeded. A key with no available permissions may still appear Active; Active describes its lifecycle, not a grant to manage resources.

Existing keys and other APIs

The scoped-key migration hashes existing secrets, preserves their original secret value for authentication, and starts them with no management permissions. Edit their scope assignments before using the account-management interfaces. Older keys without a company assignment appear with Needs company assignment; saving them explicitly assigns the selected company. They cannot authenticate until assigned. Existing exchanged api-key-token tokens are invalidated during migration because they cannot be reliably associated with a parent key; integrations must authenticate again.

To migrate an integration:

1. Select its intended company and edit the existing key.
2. Assign the resource operations it needs, set any expiry, and save. An existing company binding cannot be moved.
3. Use the original secret if you still have it, or rotate the now-active key and copy its replacement.
4. Authenticate again if the integration used an older exchanged token.
5. Export fresh definitions, update the integration's credentials, and verify a permitted Browse or Read request.

Account-management keys and their exchanged tokens are restricted to the account-management routes. They cannot be used as general mobile or session credentials. Exchanged tokens are also capped at the permissions they had when issued; authenticate again to pick up added permissions. Other API credential types retain their own authentication contracts:

Keep credentials in your integration's secret storage and use a separate key for each system.