Do you need to manage API authentication in Custobar? This guide will tell you about the scoping of API keys, and creating keys for personal (e.g. test) use as well as for integrations. It also tells you where to find your old API keys from the time before scoping API keys became mandatory.
Scoping the API keys
Personal API keys
API keys for integrations
Old API keys
Scoping the API keys
Personal API keys can be created without a scope, but integration specific API keys, which do not expire automatically, are mandatory to be scoped.
You can find the endpoint paths in our data imports and data retrieval documentation. The api endpoints in Custobar by convention have a trailing slash (/), and it needs to be included in the scope, as the path must match exactly.
Methods
- GET - retrieve data from the server. Read only.
- POST - send data to the server and create a new resource. Used to create a new data entry.
- PUT - send data to the server and update an existing resource. Used to completely update an existing data entry.
- PATCH - send data to the server and partially update an existing resource. Used to partially update an existing data entry.
- DELETE - delete a data entry from the server.
- HEAD - ask information about a document from the server, not the document itself.
Personal API keys
Personal API keys are great, for example, for testing the APIs, retrieving data or for managing things like setting up datasources and targets.
Characteristics
- Personal API keys are valid for 8 hours, after which they expire.
- Personal API keys do not need to have a scope, which makes them perfect for testing.
- The keys can also be revoked and then deleted from the user interface at any time by the person who created them.
- The keys can also be deleted by admins using the API or by contacting support@custobar.com.
- Personal API keys will stop working if a user’s account is deactivated. If the user account is activated again, the keys will resume working (as long the max. 8 hour validity has not passed).
How to manage personal API keys?
- In your Custobar environment, hover your mouse over the avatar icon in the upper right corner. Click on your own name.
- Click on the “API Keys” tab.
- In this view you can create new personal API keys, look at their details, revoke and delete them.
API keys for integrations
When you need to create API keys for long-lasting use, API keys for integrations are the solution.
Characteristics
- API keys for integrations do not expire, they have to be revoked to stop them from working.
- API keys for integrations are completely detached from the user that created them. They will not be revoked even if the user who created them is deleted or their account is disabled.
- The keys can be created, revoked and deleted from the user interface at any time by any user with Administrator level rights.
How to manage integrations’ API keys?
- In your Custobar environment, hover your mouse over the avatar icon in the upper right corner. Click on “Settings”.
- Next, click “Integrations” from the left hand menu.
- Click “Installed integrations” or “Available integrations” depending on whether you want to add or edit the API keys of an installed integration, or want to activate a new integration.
- When you have the integration on the “Installed integrations” tab, click “Configure”.
- Click on the “API Keys” tab.
- In this view you can create new, scoped, API keys for integrations, look at their details, revoke and delete them.
Old API keys
API keys that were created before the security update are still valid unless you revoke or delete them. Here’s how to find them:
- In your Custobar environment, hover your mouse over the avatar icon in the upper right corner. Click on “Manage users”.
- Click “API”. If you can't see the API tab, then your environment doesn't have old-style API keys in it.
- In this view you can see all of the old API keys created for your Custobar environment, but can’t create new keys anymore.