Skip to content

feat: add docs #4205

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Flo4604 wants to merge 4 commits into from
Closed

feat: add docs #4205

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e8c09ea
feat: add docs
Flo4604 Oct 30, 2025
6586226
fix: typo
Flo4604 Oct 30, 2025
f3baa43
fix: small doc change
Flo4604 Nov 3, 2025
48705ad
[autofix.ci] apply automated fixes
autofix-ci[bot] Nov 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 99 additions & 0 deletions apps/docs/concepts/identities/credits.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
---
title: Credits
description: "Identities can be used to share credits across multiple keys"
---

<Tip>
Identities are in public beta, please report any issues you encounter:
[support](mailto:support@unkey.dev).
</Tip>

## Sharing credits

Identities let you share a credit pool across multiple keys. For example, if you want to give a user 1000 credits per month:

Without identities: Setting 1000 credits per key means a user with 3 keys gets 3000 total credits (1000 × 3).

With identities: Create an identity with 1000 credits and associate all the user's keys with it. Now all keys share the same pool of 1000 credits.

## How it works

When you configure credits on an identity:

1. **Shared counter**: All keys associated with the identity draw from the same credit counter
2. **Automatic refills**: You can configure automatic refills (daily or monthly) to reset credits periodically

When a key with identity credits is verified, the credit cost is deducted from the shared identity counter, ensuring consistent usage tracking across all of the user's keys.

## Example use case

Let's say you're building a SaaS product with different subscription tiers:

- **Free tier**: 100 credits per day
- **Pro tier**: 10,000 credits per month
- **Enterprise**: Unlimited (no credits configured)

When a user signs up for the Pro tier:

```typescript
// Create the identity with credits
const identity = await unkey.identities.createIdentity({
externalId: user.id,
credits: {
remaining: 10000,
refill: {
interval: "monthly",
amount: 10000,
refillDay: 1, // Refill on the 1st of each month
},
},
});

// Create keys for the user
const key1 = await unkey.keys.create({
apiId: "api_123",
identityId: identity.id,
});

const key2 = await unkey.keys.create({
apiId: "api_123",
identityId: identity.id,
});
```

Now both `key1` and `key2` share the same 10,000 credits. If the user consumes 3,000 credits with `key1`, they'll have 7,000 credits remaining for both keys combined.

### Updating tiers

When a user upgrades or downgrades their subscription, you can update their credits accordingly:

```typescript
// User upgrades from Pro to Enterprise (unlimited)
await unkey.identities.updateIdentity({
identityId: identity.id,
credits: null, // Remove credit limits for unlimited usage
});

// User downgrades from Pro to Free tier
await unkey.identities.updateIdentity({
identityId: identity.id,
credits: {
remaining: 100,
refill: {
interval: "daily",
amount: 100,
},
},
});
```

When you update the credits configuration, all keys associated with the identity will immediately use the new credit limits. This makes it easy to handle subscription changes without having to update each individual key.

<Info>
API reference for creating identities: [/api-reference/v2/identities/create-identity](https://www.unkey.com/docs/api-reference/v2/identities/create-identity)

API reference for creating keys: [/api-reference/v2/keys/create-api-key](https://www.unkey.com/docs/api-reference/v2/keys/create-api-key)

API reference for verifying keys: [/api-reference/v2/keys/verify-api-key](https://www.unkey.com/docs/api-reference/v2/keys/verify-api-key)

</Info>
61 changes: 48 additions & 13 deletions apps/docs/concepts/identities/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,14 @@ title: Overview
description: "Identities are a representations of a user, an org or a machine in your application."
---


<Tip>
Identities are in in public beta, please report any issues you encounter: [support](mailto:support@unkey.dev).
Identities are in public beta, please report any issues you encounter:
[support](mailto:support@unkey.dev).
</Tip>

Identities are used to map your users, organizations, or even machine-users in Unkey and allow you to share metadata and configuration across multiple keys.
Identities are used to map your users, organizations, or even machine-users in Unkey and allow you to share metadata and configuration across multiple keys.
An identity is directly linked via a unique identifier from your system and you can associate as many keys as you want with an identity.


## Use cases

### Multiple keys for the same user
Expand All @@ -20,36 +19,72 @@ It is very common to issue multiple keys for the same user, but managing metadat

Instead of updating each key, you can update the identity and all keys associated with it will automatically get the updated metadata and configuration.


### Sharing ratelimits across multiple keys

If you have multiple keys for the same user, you can set ratelimits for the identity and share it across all keys. This way, you can ensure that the user does not exceed the ratelimits across all of their keys.

[Read more](/concepts/identities/ratelimits) about how to share ratelimits across multiple keys.

### Sharing credits across multiple keys

When you configure credits on an identity, all keys associated with that identity will share the same credit counter. This is useful when:

- A user has multiple devices or API keys and you want to track their total usage across all keys
- You want to enforce a single usage limit per user, regardless of how many keys they have
- You're building a subscription-based product where credit limits are tied to the user, not individual keys

When a key with identity credits makes a request, the credits are deducted from the shared identity counter. This ensures that the total usage across all of a user's keys doesn't exceed their allocated credits.

**Example:** If an identity has 1000 credits and a user creates 3 keys linked to that identity, all 3 keys will share the same 1000 credits. If key A uses 400 credits, keys B and C together can only use the remaining 600 credits.

[Read more](/concepts/identities/credits) about how to share credits across multiple keys.

### Aggregated analytics

If you are building a multi-tenant product, you can associate all keys of an organization with the organization's identity. This way, you can aggregate analytics across all keys of the organization and provide insights to the organization admin or drive your billing.


## Data model

<ParamField body="id" type string required>
The unique identifier of the identity in Unkey. You may use this to reference the identity in other API calls.
<ParamField body="id" type="string" required>
The unique identifier of the identity in Unkey. You may use this to reference
the identity in other API calls.
</ParamField>

<ParamField body="externalId" type="string" required>
The id of the identity in your system. This is used to link the identity in Unkey to your system.
For example your user id, or organization id if you are linking an organization.

If you are using a 3rd party auth provider like Clerk, WorkOS, or Auth0, they will provide you a unique id for users and organizations. This is what you should use as the externalId.

If you are using a 3rd party auth provider like Clerk, WorkOS, or Auth0, they will provide you a unique id for users and organizations. This is what you should use as the externalId.
We want to build deeper integrations with them, so if you are using one of these, please let us know so we can prioritize it.

We want to build deeper integrations with them, so if you are using one of these, please let us know so we can prioritize it.
</ParamField>


<ParamField body="meta" type="json">
A JSON object that can store any additional information about the identity.
We do not make assumptions about this data, it's entirely up to you to decide what to store here.
A JSON object that can store any additional information about the identity. We
do not make assumptions about this data, it's entirely up to you to decide
what to store here.
</ParamField>

<ParamField body="ratelimits" type="array">
An array of ratelimit configurations that apply to all keys associated with this identity.
When configured, all keys linked to the identity will share these ratelimits, ensuring
that the total usage across all keys doesn't exceed the specified limits.

[Read more](/concepts/identities/ratelimits) about sharing ratelimits.
</ParamField>

<ParamField body="credits" type="object">
Credit configuration for the identity. When configured, all keys associated with this
identity will share the same credit counter. This is useful for enforcing usage limits
per user regardless of how many keys they have.

The credits object contains:
- `remaining` (number): The current number of credits available
- `refill` (object, optional): Automatic refill configuration
- `interval` ("daily" | "monthly"): How often credits refill
- `amount` (number): How many credits to add on refill
- `refillDay` (number, optional): Day of month for monthly refills (1-31)

[Read more](/concepts/identities/credits) about sharing credits.
</ParamField>
2 changes: 1 addition & 1 deletion apps/docs/concepts/identities/ratelimits.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: "Identities can be used to share ratelimits across multiple keys"
---

<Tip>
Identities are in in public beta, please report any issues you encounter: [support](mailto:support@unkey.dev).
Identities are in public beta, please report any issues you encounter: [support](mailto:support@unkey.dev).
</Tip>

## Sharing ratelimits
Expand Down
43 changes: 12 additions & 31 deletions apps/docs/docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,9 +79,7 @@
},
{
"group": "Identities",
"pages": [
"quickstart/identities/shared-ratelimits"
]
"pages": ["quickstart/identities/shared-ratelimits"]
}
]
},
Expand Down Expand Up @@ -117,7 +115,8 @@
"icon": "fingerprint",
"pages": [
"concepts/identities/overview",
"concepts/identities/ratelimits"
"concepts/identities/ratelimits",
"concepts/identities/credits"
]
}
]
Expand All @@ -135,9 +134,7 @@
"pages": [
{
"group": "Ratelimiting",
"pages": [
"apis/features/ratelimiting/overview"
]
"pages": ["apis/features/ratelimiting/overview"]
},
"apis/features/temp-keys",
"apis/features/remaining",
Expand Down Expand Up @@ -172,10 +169,7 @@
{
"group": "Audit logs",
"icon": "scroll",
"pages": [
"audit-log/introduction",
"audit-log/types"
]
"pages": ["audit-log/introduction", "audit-log/types"]
},
{
"group": "Analytics",
Expand All @@ -197,10 +191,7 @@
{
"group": "Migrating API Keys",
"icon": "plane",
"pages": [
"migrations/introduction",
"migrations/keys"
]
"pages": ["migrations/introduction", "migrations/keys"]
}
]
},
Expand Down Expand Up @@ -282,9 +273,7 @@
},
{
"group": "Too Many Requests",
"pages": [
"errors/user/too_many_requests/query_quota_exceeded"
]
"pages": ["errors/user/too_many_requests/query_quota_exceeded"]
},
{
"group": "Unprocessable Entity",
Expand Down Expand Up @@ -390,15 +379,11 @@
},
{
"group": "Go",
"pages": [
"libraries/go/api"
]
"pages": ["libraries/go/api"]
},
{
"group": "Python",
"pages": [
"libraries/py/api"
]
"pages": ["libraries/py/api"]
}
]
},
Expand All @@ -423,15 +408,11 @@
},
{
"group": "Nuxt",
"pages": [
"libraries/nuxt/overview"
]
"pages": ["libraries/nuxt/overview"]
},
{
"group": "Rust",
"pages": [
"libraries/rs/overview"
]
"pages": ["libraries/rs/overview"]
},
{
"group": "Springboot",
Expand Down Expand Up @@ -474,4 +455,4 @@
"codeblocks": "system"
},
"theme": "maple"
}
}