Service Integrations and API Keys

A Service Integration is a machine identity in Admin Portal that represents a program or service consuming the PubNub Admin API identified by an API key.

Use Service Integrations to programmatically manage your PubNub account, apps, and keysets without using the Admin Portal UI. Service Integrations uses include:

• Automation scripts that create apps and keysets as part of CI/CD pipelines
• Partner customer onboarding that automatically provisions PubNub resources for new customers
• Infrastructure as code tools like Terraform that manage PubNub configuration
• AI-powered development tools like the PubNub MCP Server that need programmatic Admin API access

Service integrations and API keys

Service Integrations authenticate using API keys. A single Service Integration can have up to three API keys. For information on creating API keys, refer to Create an API Key.

API Keys can have limited permissions and expiration dates. Each Service Integration has a distinct identity for tracking and no interactive login is required for programmatic access.

API keys are only shown once at creation time. If you've lost an API key, create a new one in the same Service Integration, then revoke the old key. The new API key will have the same permissions as the old one.

Permissions model

When you create a Service Integration, you assign permissions that control what operations it can perform. Always follow the principle of least privilege by granting only the minimum permissions required for the intended use case.

Permission levels

Permissions operate on three hierarchical levels:

Resource	Scope	Example
Account	All apps and keysets in your account	Read usage metrics for the entire account.
Application	A specific app and all its keysets	Manage keysets within a single app.
Keyset	A single keyset	Configure features on one keyset.
Secret key	Secret key of a specific keyset	Manage or rotate a specific secret key.
Usage & Monitoring	Usage metrics	Read usage metrics for the entire account, apps, and keysets. Only supports read permissions.
OEM Customer	Partner Portal management	List, create and manage Partner Customers

Permissions granted at a higher level automatically apply to all resources below it. For example, granting usage:read at the application level also grants it for all keysets in that app.

Available permissions

Permission	Description
apps:read	List and view app details
apps:write	Create and update apps
keysets:read	List and view keyset details, including publish and subscribe keys
keysets:write	Create and update keysets
usage:read	View usage and billing metrics

API key permission example

Consider an account with the following structure:

• App 1: Keyset A, Keyset B
• App 2: Keyset C

Permission grant	Access granted
usage:read at account level	Can read usage for App 1, App 2, and all three keysets (A, B, C)
usage:read at App 1 level	Can read usage for App 1, Keyset A, and Keyset B only
usage:read at Keyset A level	Can read usage for Keyset A only

Permissions are immutable

You can't change the permissions of an existing Service Integration after creation. If you need different permissions, create a new Service Integration.

Create a Service Integration

To create a Service Integration:

1. Log in to the Admin Portal.

2. Click your account name in the top-right corner and select My Account.

3. Navigate to the Service Integrations tab.

4. Click Create Service Integration.

5. Enter a descriptive name for the integration (for example, "CI/CD Pipeline" or "Terraform").

6. Select the permissions the integration needs. Remember to follow the principle of least privilege.

7. Choose the scope for each permission (account, app, or keyset level).

8. Choose an expiration date for the initial API key.

9. Click Create and copy the generated API key immediately, as you won't be able to view it again.

Create an API Key

Store your API key securely

Store the API key in a secure location such as a secrets manager, environment variable, or encrypted configuration file. Never commit API keys to source control.

To get the API key, you need to have or create a service integration.

1. Log in to the Admin Portal.

2. Click your account name in the top-right corner and select My Account.

3. Navigate to the Service Integrations tab.

4. Find the Service Integration (or create a new one) to create an API key for.

5. Click + Generate API Key.

6. In the dialog that appears, choose the expiration date for the API key.

7. Click Generate API Key and copy the generated API key, as you won't be able to view it again.

API key lifecycle

API keys have built-in security controls to limit exposure.

Maximum number of API keys

You can have up to three active API keys in your account

Expiration

• API keys have a maximum time to live of 1 year
• You can configure shorter expiration periods when creating the key
• Expired keys stop working immediately and can't be renewed

Rotation

As each Service Integration can have 3 API keys, you can rotate or revoke API keys within one Service Integration.

Revocation

To immediately revoke an API key:

1. Navigate to My Account → Service Integrations.

2. In the Service Integrations table, click the row of the Service Integration whose API key you want to revoke.

3. In the Active API Keys table, click the Revoke API key link for the API key you want to revoke. A dialog will appear asking you to confirm the revocation.

The API key stops working immediately after deletion.

API key usage

You can use API keys to authenticate with the Admin API and the PubNub MCP Server.

Best practices

Follow these best practices when working with Service Integrations:

Practice	Description
Use descriptive names	Name integrations after their purpose (for example, "Production Deployment Pipeline")
Minimize permissions	Grant only the permissions each integration actually needs
Set short expiration	Use the shortest practical expiration period for your use case
Rotate regularly	Replace API keys periodically, even before they expire
Monitor usage	Review which integrations are active and remove unused ones
Use separate integrations	Create distinct integrations for different environments (dev, staging, production)