---
title: "Authentication"
description: "How to authenticate pkgplane API requests, the rate limits, and the status codes authentication can return."
---

> Documentation Index
> Fetch the complete documentation index at: https://pkgplane-docs.richaisolutions.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

Send an API key in the `Authorization` header:

```http
GET /api/me HTTP/1.1
Host: pkgplane.richaisolutions.com
Authorization: Bearer pkp_9f86d081…
```

The API base URL is `https://pkgplane.richaisolutions.com/api`. Requests from the website use the
session cookie instead, and need no header.

## API keys

| Property         | Value                                                            |
| ---------------- | ---------------------------------------------------------------- |
| Format           | `pkp_` and 64 lowercase hex characters, 68 characters in all     |
| Header           | `Authorization: Bearer <key>`, scheme case-insensitive           |
| Rate limit       | 120 requests per 60 seconds, per key                             |
| Keys per account | 25                                                               |
| Expiry           | 1 to 365 days, or never; set at creation                         |
| Statuses         | `active`, `disabled`, `expired`. Only `active` keys authenticate |

A request that has an `Authorization` header is judged on its key alone, even if it also carries a
session cookie. A request with a malformed or unknown key fails. It doesn't fall back to the session.

## Which credential an endpoint accepts

| Accepts                 | Endpoints                                        |
| ----------------------- | ------------------------------------------------ |
| Nothing (public)        | `GET /api/health`                                |
| A session or an API key | `GET /api/me`                                    |
| A session only          | `/api/api-keys/*`                                |
| An admin's session only | `/api/invitations/*`, except accepting an invite |

[Endpoints](https://pkgplane-docs.richaisolutions.com/reference/endpoints/) lists every endpoint.

## Status codes

| Status                  | Meaning                                                                                                                               | What to do                                                       |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `401 Unauthorized`      | No credential; the key is malformed, unknown, disabled or expired; its owner is banned; or the endpoint needs a session and got a key | Check the key, or [create a new one](https://pkgplane-docs.richaisolutions.com/guides/create-an-api-key/) |
| `403 Forbidden`         | Signed in, but not allowed: not an admin, or acting as another user                                                                   | Use an account with access                                       |
| `429 Too Many Requests` | The key went over 120 requests a minute                                                                                               | Wait for the seconds in `Retry-After` (60), then retry           |

The response body follows the [error format](https://pkgplane-docs.richaisolutions.com/reference/errors/):

```json
{ "error": { "message": "Unauthorized" } }
```

Source: https://pkgplane-docs.richaisolutions.com/reference/authentication/index.mdx