API Keys

API keys provide a secure way to authenticate your applications when making requests to the Pulse API without using a user login. They’re particularly useful for server-to-server integrations, automated tools, and background processes.

API Key Permissions

Each API key has specific permissions associated with it. These permissions determine what actions the API key can perform. When creating or updating an API key, you can assign any of the permissions available to your account.

Common permissions include:

readApplications - View application data
writeApplications - Create and modify applications
readMerchants - View merchant data
writeMerchants - Create and modify merchant data

API Key Accounts

API Keys are attached directly to a single account. If you do not specify the x-account-id header in your request for creating a new API key it will automatically be created for your primary account.

Managing API Keys

Creating an API Key

POST /apikeys

To create a new API key, you must have the writeApiKeys permission.

Output:

The response includes the API key and secret. This is the only time you’ll receive the full API secret, so store it securely.

Listing API Keys

GET /apikeys

Returns a list of all API keys for your account.

Output:

Updating an API Key

PATCH /apikeys/{id}

Updates an API key’s properties.

Output:

Deleting an API Key

DELETE /apikeys/{id}

Permanently deletes an API key.

Output:

Using API Keys for Authentication

There are two ways to authenticate with API keys:

1. Session-based Authentication (Recommended)

First, obtain a session token by logging in with your API key:

POST /auth/login

Output:

Then, use the session token in the Authorization header for subsequent requests, this is identical to the same process for logging in with a user name and password and using the session token provided from that to perform operations.

Authorization: Bearer your-session-token

2. Direct API Key Authentication

For simple use cases, you can just pass the API key and secret directly in headers:

x-api-key: apiKey-xxxxxxxxxxxx
x-api-secret: xxxxxxxxxxxxxxx

Which method should I use?

TLDR; Use session based auth.

The only appropriate use case for direct api key auth is for testing or maintenance reasons where establishing a session to perform a quick update locally on your machine may be more than needed for a quick simple task.

Best Practices

Store Securely: API keys and secrets should be stored securely and never committed to version control.
Limit Permissions: Only assign the permissions that your integration actually needs.
Set Expirations: Consider setting expiration dates for your API keys for enhanced security.
Rotation: Regularly rotate your API keys to minimize the impact of potential security breaches.
Monitoring: Monitor API key usage and investigate any suspicious activity.

References

For more info see the API Reference section on these items:

POST /apikeys

GET /apikeys

PATCH /apikeys/{id}

DELETE /apikeys/{id}

POST /auth/login