API Keys
Learn how API keys work on Dub
API keys on Dub allow you to access your workspace programmatically. This is useful for integrating Dub into your application or with other tools and services.
Each API key is tied to a specific workspace – meaning you can use it to access that workspace’s resources without having to worry about “leaking” access to other workspaces.
Secret and publishable keys
There are two types of API keys on Dub – Secret keys and Publishable keys.
Here are the key differences between them:
| Type | Format | When to use |
|---|---|---|
| Secret | dub_xxxxxxxx | Use this key to authenticate requests on your server. By default, you can use this key to perform any API request without restriction, so it must be stored securely in your app’s server-side code (such as in an environment variable or credential management system). Don’t expose this key on a website. |
| Publishable | dub_publishable_xxxxxxxx | Use this key to authenticate requests on the client side for operations like client-side click tracking and generating QR codes programmatically with a custom logo. |
Create a secret API key
You can create an API key by following these steps:
Go to your workspace
Go to Settings > API Keys in your workspace.
Create an API Key
Click on the “Create” button and select permissions you want to grant to the API key.
Select between “You” and “Machine” to associate the API key with your account or a machine user.
- You: This API key is tied to your user and can make requests against the selected workspace.
- Machine: A machine user will be added to your workspace, and an API key associated with that machine user will be created.
When making API calls, if your API Key have insufficient permissions, the error should tell you which permissions you need.
Make sure to copy your API key and store it in a safe place. You won’t be able to see it again.
Use your API Key
Now that you have your API key, you can use it to access your workspace’s resources programmatically via SDKs or within any API request as a bearer token.
Authorization: Bearer dub_xxxx
We recommend creating API keys with the least privilege necessary to perform the required tasks. This helps to reduce the risk of unauthorized access to your workspace.
Create a publishable API key
To create a publishable key, you can go to Settings > API Keys and click on Create publishable key. The key will be in the format dub_publishable_xxxxxxxx.
Publishable keys are currently in beta. If you’d like access, reach out to us via email.
API key permissions
When creating a secret key, you can select the permissions it has, which will give the key access to certain (or all) resources on Dub. Here are the different permission options:
| Permission | Description |
|---|---|
| All permissions | This API key will have full access to all resources. |
| Read only | This API key will have read-only access to all resources. |
| Restricted | This API key will have restricted access to some resources: |
Depending on your use case, you might want to use one of these 3 options to limit the scope of the API key and improve security.
You can only set permissions on Secret keys. Publishable keys only have access to certain endpoints, and cannot be restricted.
Machine users
On Dub, you can create API keys that are associated with a “Machine user”. This is particularly helpful when you don’t want to associate the API key with a particular user in your workspace, to avoid security risks in involving turnover or changes in project ownership.
These machine users will show up on your workspace’s People tab, but will not contribute to your workspace’s user count.
If you delete an API key associated with a machine user, the machine user will be deleted. Vice versa, if you delete a machine user, their corresponding API key will be deleted as well.
Machine users are available exclusively to workspace owners. If you are not the owner of the workspace, this option will be disabled when creating an API key.
Was this page helpful?