API keys

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

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.

1. In the left navigation bar, press Automations.

2. In the Development section, press API keys.

3. In top right of the page, press Create API key.

4. In the Description field, enter a recognizable name for the key.

5. In the Type section, select Secret or Publishable.

6. Optionally, in the Organizations dropdown, select an organization to associate with the key.

7. Optionally, in the Allowed IPs field, enter IP addresses that are permitted to use the API key, with one address per line.

   To permit all IP addresses, leave the Allowed IPs field empty.

8. 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.

9. 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.

   1. Select Limited access.

   2. Select from the following:

      Use preset permissions

      1. 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.
      2. In the Selected permissions section, review the assigned permissions.
      3. 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

      1. In the Search permissions field, enter a resource, action, or operation ID.
      2. 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.

      1. Press Paste permissions.
      2. 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 *.

10. Press Save API key to store the API key.

11. 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.

1. In the left navigation bar, press Automations.
2. In the Development section, press API keys.
3. 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.

1. In the left navigation bar, press Automations.
2. In the Development section, press API keys.
3. Optionally, if you have not created a publishable key, create one. For more information, see Create an API key.
4. 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.

1. In the left navigation bar, press Automations.
2. In the Development section, press API keys.
3. 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.
4. 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.

1. In the left navigation bar, press Automations.

2. In the Development section, press API keys.

3. In the API keys table, under the Description column, press a secret key.

4. Select from the following:

   • To add the IP address of the last request that used the key: Under the Allowed IPs field, 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.

5. Press Save API key.

Use this process to edit or delete an API key.

1. In the left navigation bar, press Automations.

2. In the Development section, press API keys.

3. Select from the following:

   Edit an API key

   1. In the API keys table, under the Name column, press an API key.
   2. 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.

1. In the left navigation bar, press Automations.
2. In the Development section, press API keys.
3. In the API keys table, under the Name column, press an API key.
4. 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.
5. 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.

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.

• User permissions
• Users