This topic describes API keys and how to use them in Rebilly.
The following key types are available:
- Secret key: Use to authenticate requests on a server. Secret keys can have full access to perform any API request, or limited access to specific API operations. Secret keys must be kept secret and stored securely in the server-side code of your web or mobile application.
- Publishable key: Use to tokenize payment information in your client-side code. Publishable keys are publicly accessible in a web browser or mobile application. Publishable keys are mainly used to create tokens, which are a representation of a payment source that hides sensitive information.
When interacting with the Rebilly API, you use your organization ID and secret key to authenticate requests. This CURL request describes how to authenticate a request using a secret key. To obtain your secret key, see Obtain a secret key. To obtain your organization ID, see Obtain an organization ID.
curl 'https://api-sandbox.rebilly.com/organizations/your_organization_id' \
-H 'REB-APIKEY: your_secret_API_key'
API keys use the following format: type_environment_tokenizedPayload
| Type of key | Example |
|---|---|
| Secret key in the sandbox environment | sk_sandbox_K7W_ZG1OvxkXmtDx2kaE39IN2YZF0INVcqsdgXl |
| Publishable key in the live environment | pk_live_CaDB_u9Jb6JeeaR_p811KmwiGTyJOmg1WInsmuo |
This section describes how to manage API keys.
Use this process to create new API keys. A secret key is displayed in full only once, after you create it. Before you close the dialog that displays the key, store the key in a secure place.
In the left navigation bar, press Automations.
In the Development section, press API keys.
In top right of the page, press Create API key.
In the Description field, enter a recognizable name for the key.
In the Type section, select Secret or Publishable.
Optionally, to change the organizations where the key can be used: In the Organizations dropdown, select the organizations.
The organization that you are working in is selected by default. Requests that use the key are authorized only in the selected organizations. If no organization is selected, requests that use the key are authorized in all organizations that you are a member of.Select from the following:
- To restrict the key to specific IP addresses: Under IP access, select Allowed IPs only.
In the Allowed IPs field, enter one IP address or Classless Inter-Domain Routing (CIDR) range per line. Requests made using the key from other IP addresses are rejected. This option is recommended for all secret keys. Enter the outbound IP addresses of your servers. - To permit the key to be used from any IP address: Under IP access, select Any IP address.
If a secret key is exposed, anyone with access to it can send requests from any IP address. Publishable keys are used in the web browsers of your customers, so this option is appropriate for most publishable keys.
- To restrict the key to specific IP addresses: Under IP access, select Allowed IPs only.
In the Expiration dropdown, select when the API key stops working:
- 7 days, 30 days, 60 days, or 90 days: The API key expires that number of days from now.
- Custom: In the Expiration date field, select a date and time.
- No expiration: The API key does not expire.
For a secret key, 30 days is selected by default. For a publishable key, No expiration is selected by default. For more information, see Set or remove an expiration date.
In the API key permissions section, select from the following:
Grant full access to the API key
Select Full access.
Grant limited access
To follow the principle of least privilege, grant only the API operations that the key requires.
Select Limited access.
Select from the following:
Use preset permissions
- Select one of the following presets:
- Admin role: Grants all edit and view permissions.
- Customer service agent: Grants permissions for customers, invoices, and transactions.
- Settings manager: Grants permissions for products, plans, gateways, and automations.
- Accountant: Grants permissions for reports, billing data, and financial settings.
- KYC agent: Grants permissions for KYC documents, tags, and custom fields.
- In the Selected permissions section, review the assigned permissions.
- Optionally, to change the assigned permissions: Expand a resource section and select or clear the checkbox beside a resource or permission.
Search and assign permissions
- In the Search permissions field, enter a resource, action, or operation ID.
- Select or clear the checkbox beside a resource or permission.
Paste a list of permissions
Use this process to set permissions for this API key by pasting operation IDs. Permissions that are not in the pasted list are removed. For a list of all permissions and operation IDs, see User permissions.
- Press Paste permissions.
- In the Permissions field, enter the operation IDs.
Separate operation IDs with new lines, commas, spaces, or semicolons, or paste a JSON array.
To grant the API key full access, enter*.
- Select one of the following presets:
Press Save API key to store the API key.
If you created a secret key: Press Copy, store the key in a secure place, and press Done.
After you press Done, the full secret key cannot be displayed again.
Use this process to view and obtain API keys. The API keys table displays the full value of publishable keys only. For a secret key, only the key type, the environment, and the API user name are displayed, and the rest of the key is masked. To obtain a secret key, see Obtain a secret key.
- In the left navigation bar, press Automations.
- In the Development section, press API keys.
- In the API keys table, under the Key column, beside a publishable key, press Copy.
Use this process to obtain a publishable API key. This key is required to interact with the Rebilly API.
- In the left navigation bar, press Automations.
- In the Development section, press API keys.
- Optionally, if you have not created a publishable key, create one. For more information, see Create an API key.
- Select a publishable key and copy the Key value.
A secret key is displayed in full only once, after you create it. For an existing secret key, the API keys table and the API display only the key type, the environment, and the API user name. To obtain a secret key, create one and copy it from the dialog that displays the key. For more information, see Create an API key.
If you lose a secret key, create a new secret key, update your server-side code to use it, and delete the old key. For more information, see Edit or delete an API key.
Use this process to find API keys that are no longer used, or that are used from an unexpected IP address. The last use of an API key is the most recent request that used the key. Requests are recorded from October 28, 2026. If an API key has not been used since that date, the Last used column is empty.
- In the left navigation bar, press Automations.
- In the Development section, press API keys.
- Optionally, to display the IP address of the last request: In the top right of the table, press Edit columns, select Last used IP, and press Apply.
- In the API keys table, in the Last used column, view the date and time of the last request that used each key.
Use this process to limit an existing secret key to the IP addresses of the servers that use it. A secret key with no allowed IPs can be used from any IP address.
After you save allowed IPs, requests that use the key from other IP addresses are not authorized. Before you save, include every IP address that your integration sends requests from.
In the left navigation bar, press Automations.
In the Development section, press API keys.
In the API keys table, under the Description column, press a secret key.
Under IP access, select Allowed IPs only.
Select from the following:
- To add the IP address of the last request that used the key: Under IP access, press Add to allowed IPs.
This link is displayed only when the key has been used and the IP address of its last request is not already allowed. Before you press the link, check that the IP address and the date of the last request match your server. If someone else has a copy of the key, the last request might be from their IP address. - To add other IP addresses: In the Allowed IPs field, enter the outbound IP addresses of your servers, with one IP address per line.
Existing allowed IPs stay in the list unless you remove them.
- To add the IP address of the last request that used the key: Under IP access, press Add to allowed IPs.
Press Save API key.
Use this process to edit or delete an API key.
Key deletion is permanent.
In the left navigation bar, press Automations.
In the Development section, press API keys.
Select from the following:
Edit an API key
- In the API keys table, under the Description column, press an API key.
- Edit the API key details and permissions, then press Save API key.
Delete an API key
In the API keys table, on the right of an API key, press Delete.
Use this process to stop an API key from working after a set time, or to remove that limit from an API key. From the expiration date, a request that uses the API key is not authorized, and a 401 Unauthorized response is returned. An API key without an expiration date does not expire. If an API key has an expiration date, Custom is selected in the Expiration dropdown, and the Expiration date field displays that date. To save changes to an API key that has already expired, set a new expiration date or remove the expiration date.
Seven days before an API key expires, the user who owns the API key receives one email reminder for that expiration date. If the API key is created with seven days or less until it expires, the user receives the reminder 24 hours after the API key is created. If the expiration date changes, the user receives one email reminder for the new expiration date.
- In the left navigation bar, press Automations.
- In the Development section, press API keys.
- In the API keys table, under the Description column, press an API key.
- In the Expiration dropdown, select from the following:
The new selection replaces the existing expiration date.- To expire the API key after a preset period: Select 7 days, 30 days, 60 days, or 90 days.
- To expire the API key at a specific date and time: Select Custom, and in the Expiration date field, select a date and time.
- To remove the expiration date: Select No expiration.
- Press Save API key.
To set an expiration date with the API, include the expirationTime field in Create an API key or Upsert an API key. If expirationTime is not in the future, a validation error is returned. If an upsert request omits expirationTime, the expiration date is not changed. To remove the expiration date, set expirationTime to null.
An API key is associated with the user who creates it. The API key cannot be assigned to another user.
A request that uses the API key is authorized only when the API key includes the required permission and the associated user has that permission.
If the API key includes *, a request is authorized only for an operation the associated user is permitted to perform. If a user loses a permission and the API key still includes that permission, a request that requires that permission is not authorized. If a user gains a permission, a request that requires that permission is authorized only when the API key includes that permission or *. When a user is removed from an organization, requests to that organization that use the API key are not authorized.
An API key is not associated with a role. To set the permission list on an API key, use Create an API key and include the acl field. To assign permissions to users with a role, see Create roles.
Use this process to view all API keys in your organization, check which users have API keys, or audit API keys after suspected exposure. All API keys in your organization are listed, except keys with permissions that grant access only to other organizations. The full values of publishable keys are displayed. For secret keys, only the key type, environment, and API user name are displayed. The rest of each secret key is masked.
You cannot open, edit, or delete API keys owned by other users. To revoke an API key, the user who owns it must delete it. To block the API keys of a user in your organization only, delete the user. Deleting the user removes them from your organization, but does not delete their API keys. Their API keys still work in their other organizations, and work in your organization again if the user rejoins it. For more information, see View users, delete users, or emulate a user's permissions.
To retrieve all API keys in your organization using the API, see Retrieve organization API keys.
To complete this process, you must have the administrator role, or a role with the GetApiKeyCollection and GetOrganizationApiKeyCollection permissions. For more information, see User permissions.
- In the left navigation bar, press Automations.
- In the Development section, press API keys.
- In the top right of the page, press View organization API keys.
- Optionally, to display more columns, such as Last used IP: In the top right of the table, press Edit columns, select the columns, and press Apply.
- In the Owner column, view the name and email address of the user who owns each API key.
- In the Allowed IPs column, view which secret keys can be used from any IP address.
To identify the organization for the API request, always include the organizationId in the request URL. Example: https://api-sandbox.rebilly.com/organizations/{organizationId}/customers.
A user may be a member of one or more organizations, and may also join or leave organizations. For information on how access for an API key follows that user, see Ownership of an API key.
To associate an API key with an organization, when you create or edit a key, in the Organizations dropdown, select an organization. For more information, see Create an API key or Edit an API key.