# Authentication

All Platform API requests require an API key. The API key identifies your organization and grants access to the partners, flows, and results within it.

## API Keys

API keys are managed from the **API Keys** page in the application. Each key belongs to your organization and has a name for your reference.

To create a key:

1. Open the **API Keys** page
2. Click **Add API Key**
3. Enter a name (for example "Production" or "Staging")
4. Choose a scope: **Standard** or **Read-only**
5. Click **Submit**

The key is displayed only at creation time. Copy it immediately and store it securely: it is never shown again, and the list that follows carries the key's name, scope, and creator, never the key itself. If you lose one, delete it and create another.

You can create multiple API keys for different environments or integrations.

## Key Scope

The list shows each key's scope, and the endpoint pages say which scope they need.

Scope is set when the key is created and cannot be changed afterwards. To change it, create a new key and delete the old one.

- **standard**: reaches your whole organization and can read, send, resend and receive documents.
- **read_only**: reads everything a standard key reads, including your partners and configuration, the X12 reference and the inspector, and changes nothing. Any request other than `GET` or `HEAD` under `/platform/` is refused with `403 forbidden`. Give one to an agent that only investigates, so it cannot send or resend a document on its own.
- **sandbox**: issued automatically when you set up a sandbox webhook sink, and scoped to that sandbox traffic. Organization-wide endpoints reject it with `403 forbidden`: the feed, the EDI transactions list and detail, the logs endpoint, and resend. Outside its sink it can reach only `GET /platform/whoami`, below, and `POST /platform/suggestions`.

## Making Requests

Include your API key in the `Authorization` header using the `Key` scheme:

```
Authorization: Key your-api-key-here
```

All API endpoints use the base path `/platform/` and return JSON responses.

Example request:

```bash
curl -X GET "https://tediware.com/platform/results" \
  -H "Authorization: Key your-api-key-here"
```

If the key is missing or invalid, the API returns a `401` response:

```json
{
  "error": {
    "message": "API key is missing",
    "code": "unauthorized"
  }
}
```

## Checking a Key

```
GET /platform/whoami
```

Reports the identity behind the key without reading any of your data, so it is the call to make when you want to know whether a stored key still works and what it reaches.

```json
{
  "organization": {
    "id": "0d4b6b6e-5f8a-4c31-9a2e-7f6a1c0d9b21",
    "name": "Acme Logistics"
  },
  "keyScope": "standard",
  "keyLabel": "Production",
  "serviceTermsAccepted": true
}
```

- `keyScope` is `standard`, `read_only` or `sandbox`, as described above.
- `keyLabel` is the name the key was given when it was created.
- `serviceTermsAccepted` reports whether the person who created the key has accepted the Tediware service terms. None of the endpoints in this reference check it, so `false` here does not block them. It is reported so a tool holding the key can raise it with you rather than failing partway through a run.

Every key scope can call this endpoint, sandbox included: a client should be able to ask who it is with whatever key it holds. A missing or invalid key still returns `401`, so a `200` is itself confirmation that the key is live.

```bash
curl "https://tediware.com/platform/whoami" \
  -H "Authorization: Key your-api-key-here"
```

## Revoking a Key

To revoke an API key, navigate to **Settings** then **API Keys**, find the key, and click **Delete**. Any requests using that key will immediately begin returning `401` responses.