API Keys

The API Keys page (/api-keys) lets you generate and manage API credentials for programmatic access to the Partner API. API keys are used when your systems need to access SabiBooks data outside of the portal interface — for example, to pull merchant data into your own analytics platform or to automate merchant onboarding.

Summary Cards

When you have at least one API key, three summary cards appear at the top of the page:

Total Keys

Total number of API keys created (including revoked and expired).

Active Keys

Number of keys currently in active status.

Total Requests

Cumulative number of API requests made across all your keys.

API Key Table

The table displays all your API keys with the following columns:

Column	Description
Name	The descriptive name you gave the key when creating it
Key Prefix	First few characters of the key ID, useful for identifying which key is in use
Scopes	The permissions assigned to this key
Status	Current status: ACTIVE (green), REVOKED (red), or EXPIRED (gray)
Expires At	When the key will expire (if set)
Last Used At	Timestamp of the most recent API request using this key
Request Count	Total number of API requests made with this key
Actions	Revoke button (for active keys)

Generating a New API Key

1. Open the creation dialog. Click the Generate New Key button in the top-right corner of the page.

2. Enter a key name. Give your key a descriptive name that indicates its purpose. Good examples:

   • “Production Integration”
   • “Staging Analytics Pull”
   • “Merchant Onboarding Service”

3. Select scopes. Choose which permissions this key should have (see Available Scopes below). You must select at least one scope. Follow the principle of least privilege: only grant the scopes that the consuming system actually needs.

4. Set expiration. Choose when the key should expire:

   Option	Duration
   30 days	Short-lived, good for testing or temporary integrations
   90 days	Medium-term, suitable for development environments
   1 year	Standard production lifetime (default)
   2 years	Extended lifetime for stable integrations

5. Generate. Click Generate Key. The key is created and a Secret Display dialog immediately appears.

6. Copy the secret. The dialog shows the complete API key secret. Click the Copy button to copy it to your clipboard. Store the secret securely in your system’s secrets manager, environment configuration, or vault. Once you close this dialog, the secret cannot be retrieved again.

Caution

The API key secret is shown only once at the time of creation. The portal does not store the full secret — only a prefix is retained for identification. If you lose the secret, you must generate a new key.

Available Scopes

Scope	Label	Description
merchants:read	Read Merchants	View merchant list and details
merchants:write	Write Merchants	Create and update merchants
analytics:read	Read Analytics	View partner analytics and metrics
webhooks:manage	Manage Webhooks	Configure and manage webhook endpoints
reports:read	Read Reports	Download and view reports

Revoking an API Key

1. Find the key in the table.
2. Click the Revoke button in the Actions column.
3. A confirmation dialog appears showing the key name so you can verify you are revoking the correct key.
4. Click Confirm to revoke the key.

Once revoked, the key immediately becomes invalid. Any API requests using this key will fail with an authentication error. Revocation is permanent and cannot be undone.

When to revoke a key:

• When a key may have been compromised or leaked.
• When a system that used the key is being decommissioned.
• When rotating keys as part of a security policy.

Security Best Practices

Caution

API key security is critical. A compromised key gives unauthorized access to your merchant data. Follow these practices to minimize risk.

1. Never share secrets in plain text. Do not send API key secrets via email, chat, or commit them to source code repositories.

2. Use separate keys for separate environments. Create distinct keys for development, staging, and production. This limits the impact if a key is compromised.

3. Apply least-privilege scopes. Only grant the permissions a system needs. A reporting dashboard only needs analytics:read and reports:read, not merchants:write.

4. Rotate keys regularly. Create new keys and transition your systems before old keys expire. This reduces the risk window if a key is compromised without your knowledge.

5. Monitor usage. Check the “Last Used At” and “Request Count” columns regularly. A key that has not been used recently may indicate a system issue. A key with unexpected request spikes may indicate unauthorized usage.

6. Revoke unused keys promptly. If a key is no longer needed, revoke it immediately rather than waiting for it to expire.

Best Practices

• Maintain a key inventory. Track which systems use which API keys in your internal documentation.
• Set calendar reminders for key expiration. Create new keys and transition your systems before old keys expire.
• Name keys descriptively. Include the environment and purpose in the name (e.g., “Prod - Analytics Dashboard”) so you can quickly identify keys in the table.

API Key Troubleshooting

Problem	Possible Cause	Solution
Lost API key secret	Secret was not copied after generation	Generate a new key. The old secret cannot be recovered.
API requests return 401	Key is revoked, expired, or scopes are insufficient	Check the key status in the portal. Verify the scope covers the API endpoint being called.
Key not showing in table	Page not refreshed after creation	Refresh the page to see the newly created key.
Cannot generate new key	Insufficient permissions	Only users with the PARTNER_ADMIN role can generate API keys. See Roles and Permissions.

Related Pages

Webhook Configuration Receive real-time event notifications from your merchant network.

Branding Configuration Customize the white-label appearance of the merchant app.

Partner Portal Overview Portal introduction, login, navigation, and roles.