# Authentication

> Send your personal API key as a Bearer token on every request. Where to get the key, what it can do, and how to keep it safe.

Web page: https://developer.yoprint.com/concepts/authentication/

Every request to the YoPrint API carries your personal API key in the `Authorization` header:

```http
Authorization: Bearer YOUR_API_KEY
```

There is no sign-in call and no token exchange. The key goes on every request. Integrations that already send it another way keep working. See [Other ways to send the key](#other-ways-to-send-the-key).

**Diagram:** Every request carries the key. There is no session to keep alive.

1. **Your request**: `Authorization: Bearer YOUR_API_KEY`
2. **Who you are**: YoPrint finds the key's user
3. **Which team**: The team slug in the path: you must be a member, on a plan with API access
4. **What you may do**: Your role on that team decides

## Get your API key

API access comes with the Pro plan or higher: Pro and its trial, the Special plan, and the older Essential and Enterprise plans. Basic, Free and the older Starter plan don't include it. Creating an API key in Profile also needs an active, paid subscription. On those plans, every team member can create their own key.

1. Sign in to YoPrint and open **Profile**.
2. Find the **API Access** card. If it says "You don't have an API key yet.", select **Create API Key**. Opening the page never creates a key.
3. YoPrint shows the new key in full. Copy it and store it somewhere safe, such as your app's secret store.

After that, the card shows the key masked except its last four characters. Select **Reveal** to see it again. The copy button next to it copies the whole key, masked or not.

The same card shows:

- Your **Team ID**, the [team slug](https://developer.yoprint.com/concepts/teams.md) that goes in each request's path.
- When the key was last used and, when YoPrint can tell, the kind of app that used it, such as Zapier.
- **Make your first request**: a request to copy that checks the key and the Team ID together. See [Check that a key works](#check-that-a-key-works).

> **Note:** No **API Access** card in Profile means your team's plan doesn't include API access. On a trial, Profile doesn't create keys: the card says "API keys need an active subscription. If you're on a trial and want to try the API, email support\@yoprint.com." The API itself works on a Pro trial: if you already have a key, it works on the trial team too. See [Test your integration](https://developer.yoprint.com/start/testing.md).

## What a key can do

A key acts as you.

- It has your role on each team. Most operations follow that role, but some let any member call them, so a key can sometimes do more than the web app would let you. See [Roles and permissions](https://developer.yoprint.com/concepts/roles-and-permissions.md).
- It works on every team you belong to whose plan includes API access (Pro or higher). The team slug in each request's path picks the team.
- Changes made with it are recorded under your name (the API key's user), just as if you made them directly in the web app.

Each person has one key. Everything an integration does with your key, it does as you.

## Choose whose key runs an integration

A key acts as one person, so pick the person before you build:

- **For an integration that runs on its own**, such as a nightly sync, invite a team member just for it and give it a role with only what the integration needs. Its changes are then recorded under that member's name, apart from people's own. The member counts toward your plan's user limit.
- **For a script you run yourself**, your own key is fine.
- **If that member leaves the team**, every call with their key to that team answers `404`, because the key's user is no longer a member.
- **If the key is regenerated**, every app that uses it stops working until you give it the new key.

See [Roles and permissions](https://developer.yoprint.com/concepts/roles-and-permissions.md) for choosing the role.

## Check that a key works

This is the request the **Make your first request** section of the **API Access** card shows, with your Team ID in place of `your-team`:

`GET /v1/api/store/{team_slug}/is_authenticated` [Check that your API key works for a team](https://developer.yoprint.com/reference/api-key/v1-misc-is-authenticated.md)

```bash
curl https://secure.yoprint.com/v1/api/store/your-team/is_authenticated \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json
{
  "status": 200,
  "success": true,
  "data": { "is_authenticated": true }
}
```

A `200` means the key is valid, the team exists and you're a member of it. It doesn't tell you what your role allows.

## When authentication fails

| Status | Cause                                                                                                                                                                                                | Fix                                                                                                                                                                                                                    |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | The key is missing, wrong or was replaced.                                                                                                                                                           | Send `Authorization: Bearer YOUR_API_KEY` with your current key.                                                                                                                                                       |
| `404`  | The key is fine, but the team slug is wrong or you're not a member of that team.                                                                                                                     | Check the **Team ID** in Profile.                                                                                                                                                                                      |
| `403`  | The key is fine, but the team's plan doesn't include API access (`api_access_not_in_plan`), your role doesn't allow this operation, or the call reads or changes the key itself (`self_credential`). | For the plan, see [below](#when-your-teams-plan-doesnt-include-api-access). For the role, see [Roles and permissions](https://developer.yoprint.com/concepts/roles-and-permissions.md). Manage the key in **Profile**. |

YoPrint checks the key before the team, so a wrong key always answers `401`, even when the slug is wrong too.

## Replace a key

Select **Regenerate API Key** on the **API Access** card, then **Regenerate key**. The old key stops working at once. Update every app that used it.

Your API key is separate from your browser sessions. Changing your password or email doesn't replace it. If you think your account or key was exposed, regenerate the key.

## When your team's plan doesn't include API access

The API, webhooks and Zapier need a plan with API access (Pro or higher) and an active subscription or trial. Without one, every request with a key answers `403` with the code `api_access_not_in_plan` and "Your team's plan doesn't include API access. Upgrade to the Pro plan or higher in YoPrint, under Billing, to use the API, webhooks and Zapier." The key itself keeps working on any other team you belong to whose plan includes API access.

The same rule applies to webhooks:

- A team without API access gets no webhook deliveries. Events from that time are never sent later, and the delivery log shows nothing for them.
- Through the API, every request is refused, including listing and deleting webhook subscriptions. Zapier can't remove its subscription when you turn a Zap off.
- In YoPrint's settings, the team can still list and delete its subscriptions. The settings menu hides the **Webhooks** link, but the page still opens from a direct link.
- Subscriptions are kept, and start delivering again once the team is back on a plan with API access.

## A key can't manage itself

A key can't read, create or reset itself through the API. Those calls answer `403` with the code `self_credential` and "Manage your API key in YoPrint, not through the API." Manage your key on the **API Access** card.

## Keep the key secret

- Keep it on a server. Never put it in a web page, a mobile app or a public repository.
- Send it only to `https://secure.yoprint.com`.
- Don't log it, or the `Authorization` header that carries it.

## Other ways to send the key

Existing integrations keep working as they are. Besides `Authorization: Bearer YOUR_API_KEY`, YoPrint accepts:

- the key alone in the `Authorization` header, without `Bearer`. YoPrint's Zapier app sends it this way.
- a `user_api_key` query parameter or body field. This puts the key in URLs, browser history and server logs, so don't use it for new code.

YoPrint checks for keys in this order: the `user_api_key` query parameter, the `user_api_key` body field, and finally the `Authorization` header. It evaluates only the first key it finds. If that first key is wrong or has been replaced, the request fails with `401` at once: there is no fallback to another key. For example, a request with an outdated key in `?user_api_key=` answers `401` even if the `Authorization` header carries your current valid key. Always send the key in one place only.