Skip to content

Commit

Permalink
Update tokens.mdx
Browse files Browse the repository at this point in the history
  • Loading branch information
@steven-tey
steven-tey committed Oct 5, 2024
1 parent 4bfe258 commit 7257626
Showing 1 changed file with 78 additions and 59 deletions.
137 changes: 78 additions & 59 deletions api-reference/tokens.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,75 +1,31 @@
---
title: "API Keys"
"og:title": "How to get my Dub.co API key?"
description: "Learn how to get your Dub.co API key."
description: "Learn how API keys work on Dub"
icon: key
---

API keys on Dub.co allow other apps to access your workspace programmatically. This is useful for integrating Dub with other tools and services.
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. You also no longer need to pass your [workspace ID](https://dub.co/help/article/how-to-get-workspace-id) in your API requests.
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.

<Tip>Dub API keys are prefixed with `dub_` for easy identification.</Tip>
## Secret and publishable keys

## API key permissions

You can create 3 types of API keys on Dub.co:

1. **All permissions** – This API key will have full access to all resources.
2. **Read only** – This API key will have read-only access to all resources.
3. **Restricted** – This API key will have restricted access to some resources:
- [Links](/data-model#links)
- [Analytics](/api-reference/endpoint/retrieve-analytics)
- [Workspaces](/data-model#workspace)
- [Domains](/data-model#domains)
- [Tags](/data-model#tags)
- API Keys

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.

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

<Frame>
<img
src="/images/api-machine-users.png"
alt="Creating an API key associated with a machine user on Dub"
width="1528"
height="974"
/>
</Frame>

These machine users will show up on your workspace's **People** tab, but will not contribute to your workspace's user count.

<Frame>
<img
src="/images/machine-user.png"
alt="Machine user on Dub"
width="1468"
height="249"
/>
</Frame>
There are two types of API keys on Dub – **Secret keys** and **Publishable keys**.

<Tip>
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.
</Tip>
Here are the key differences between them:

<Warning>
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.
</Warning>
| 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](/conversions/clicks/introduction#client-side-click-tracking) and [generating QR codes programmatically with a custom logo](/api-reference/endpoint/retrieve-a-qr-code). |

## How to create an API key
## Create a secret API key

You can create an API key by following these steps:

<Steps>
<Step title="Go to your workspace">
Go to **Settings** > **API Keys** in your workspace.
Go to **Settings** > [**API Keys**](https://app.dub.co/settings/tokens) in your workspace.

<Frame>
<img
Expand All @@ -85,10 +41,10 @@ You can create an API key by following these steps:
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 a user or a [machine user](#machine-users).
Select between "You" and "Machine" to associate the API key with your account or a [machine user](#machine-users).

- **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 will be created.
- **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.

<Frame>
<img
Expand Down Expand Up @@ -119,3 +75,66 @@ You can create an API key by following these steps:
the required tasks. This helps to reduce the risk of unauthorized access to
your workspace.
</Tip>

## Create a publishable API key

To create a publishable key, you can go to **Settings** > [**API Keys**](https://app.dub.co/settings/tokens) and click on **Create publishable key**. The key will be in the format `dub_publishable_xxxxxxxx`.

<Note>
Publishable keys are currently in beta. If you'd like access, [reach out to us
via
email](mailto:support@dub.co?subject=I%20want%20access%20to%20publishable%20keys).
</Note>

## 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: <ul><li>[Links](/data-model#links)</li><li>[Analytics](/api-reference/endpoint/retrieve-analytics)</li><li>[Workspaces](/data-model#workspace)</li><li>[Domains](/data-model#domains)</li><li>[Tags](/data-model#tags)</li></ul> |

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.

<Tip>
You can only set permissions on Secret keys. Publishable keys only have access
to certain endpoints, and cannot be restricted.
</Tip>

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

<Frame>
<img
src="/images/api-machine-users.png"
alt="Creating an API key associated with a machine user on Dub"
width="1528"
height="974"
/>
</Frame>

These machine users will show up on your workspace's **People** tab, but will not contribute to your workspace's user count.

<Frame>
<img
src="/images/machine-user.png"
alt="Machine user on Dub"
width="1468"
height="249"
/>
</Frame>

<Tip>
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.
</Tip>

<Warning>
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.
</Warning>

0 comments on commit 7257626

Please sign in to comment.