> For the complete documentation index, see [llms.txt](https://docs.shipide.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shipide.com/authentication.md).

# Authentication

Create and manage API keys in **Portal > Account > Developer**. Give each integration its own key so you can revoke one without interrupting others.

```http
Authorization: Bearer shipide_test_YOUR_KEY
```

`shipide_test_` keys access sandbox records. `shipide_live_` keys access live records. Both use the same API base URL. One customer's keys cannot access another customer's records, and sandbox records are isolated from live records.

The full key is shown only at creation. Shipide stores its SHA-256 hash, not the plaintext key. You can set an expiry when creating it; expired and revoked keys receive `401 invalid_api_key`.

## Permissions

| Scope             | Access                                          |
| ----------------- | ----------------------------------------------- |
| `account:read`    | Account identity, environment, and capabilities |
| `orders:read`     | List and retrieve orders                        |
| `orders:write`    | Create orders                                   |
| `shipments:read`  | List and retrieve shipments; retrieve tracking  |
| `shipments:write` | Create shipments                                |
| `rates:read`      | Request rates                                   |
| `labels:read`     | List and retrieve labels; download PDFs         |
| `labels:write`    | Create and void labels                          |
| `webhooks:read`   | List and retrieve webhook subscriptions         |
| `webhooks:write`  | Create and disable webhook subscriptions        |

Missing permissions return `403 insufficient_scope`. At most 20 active keys can be created per account. Key management requires a signed-in portal session; an API key cannot create more keys.

## Rotate a key

Create a replacement with the necessary scopes, update your backend secret, verify a request, then revoke the old key. Revocation prevents subsequent requests immediately. Never send a key in query parameters or browser-side JavaScript.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.shipide.com/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.