# Authentication

import { Mermaid } from "zudoku/mermaid";

Every request carries an API key in the `apikey` header. The key belongs to a TMS user and acts as that user: it sees
the customers, divisions and accounts that user is assigned, and nothing else.

```shell
curl -X POST "https://tmstest.reconex.io/api/v1/IntegrationApi/GetLoadInfo" \
  -H "apikey: YOUR-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{ "loadsReference": ["PO-12345"] }'
```

A request with a missing, wrong or removed key gets `403 Forbidden`, and so does a key used in the wrong environment.

:::note{title="You start in the test environment"}
Your first invitation, your first sign-in and your first API key are all in our test environment, and every request
you make while you build goes to `https://tmstest.reconex.io`. When you're ready to go live, we invite you to
production and you repeat these steps there to get a production key; see [Going live](/going-live).
:::

## Set up your TMS user

Reconex invites you to the TMS by email, to the test environment first. You never get a password from us, and nobody
at Reconex can see or set yours.

<Mermaid
  chart={`flowchart LR
  A[Invitation email] --> B[Confirm your email<br/>with a one-time code]
  B --> C[Choose your password]
  C --> D[Sign in to the TMS]
  D --> E[Your Profile: Generate API key]
  E --> F[Send it in the apikey header]`}
/>

1. **Open the invitation email** and follow its link.
2. **Confirm your email address.** You get a one-time code by email; enter it on the page.
3. **Choose your password.**
4. **Sign in** to the TMS with your email address and that password.

If you forget your password, use **Forgot password** on the sign-in page. You get a code by email and choose a new
one yourself.

## Get your API key

Do this at your first sign-in to the test environment. The key you get works only there.

1. In the TMS, open **Your Profile** (your name, top right).
2. If you don't have a key yet, choose **Generate API key**.
3. Your key shows under **API key**, masked. Copy it with the button beside it; it stays there, so you can copy it
   again any time.

Keys look like two GUIDs joined by a hyphen, in upper case, for example
`8F14E45F-CEEA-467A-9C3A-1E8B5A2F0C11-5D41402A-BC4B-4A2A-8F7D-3B9C8E1A2D4F`.

## Replace a key

A key stays the same until it's removed. To replace yours, for example if it may have leaked, ask your Reconex contact
to remove it (an administrator does that in the TMS's User Management), then generate a new one on Your Profile. The
old key stops working as soon as it's removed.

## Good practice

- Keep keys out of source code and logs; store them in your secrets manager.
- Each TMS user has one key. For a separate key per system that calls us, ask your Reconex contact for a TMS user for
  each.
- Keep your test and production keys apart, and make the base URL and key configuration, not code.