# Get an authorization token

> `POST https://api.kustom.co/auth`

Obtain a bearer authorization token. Aggregator specific merchant identifier and API key will be provided in the payload body, it's recommended that a merchant unique token is returned using a signed Json Web Token (JWT).

The token will be used for subsequent request for this merchant identifier using HTTP bearer authorization in the `Authorization` HTTP header with the format `Authorization: Bearer <token>`.

More about how this works:

When a Merchant has an agreement with the TMS, the TMS provides the Merchant with an Identifier and a Key. The Merchant then configures Kustom to use the TMS with the provided Identifier and Key. So let's say the TMS gives the Merchant these credentials:  
```
Identifier: "sweMerch123"
Key: "smOOOth"
```

As KSS prepares its authorization request to the TMS, it generates a random Nonce. KSS appends the Key to the Nonce, and then runs the Sha256 algorithm on that value to create a Digest.

To further the example, let's say KSS provided a Nonce of `'lRFUpqW7Xd'`:

```
Nonce: "lRFUpqW7Xd"
Nonce+Key: "lRFUpqW7XdsmOOOth"
Digest: "8C3891B3162DB3AB61A9B2DA74E6A479553ABA897894E5236ED290C11A0B832B"
```

Then KSS sends the authorization request with the Identifier, Nonce, and Digest.

The TMS authenticates the credentials by looking up their local Key for the Identifier, appending the Key to the Nonce provided by KSS, running the Sha256 algorithm on that value to create their own Digest, and then comparing that Digest to the Digest provided by KSS. If the Digests are identical, the TMS accepts the request and returns a bearer token.

## Request body

`application/vdn.klarna.shipping.auth-v1+json`

- `identifier` (string) — Handled as a string. Should uniquely identify the merchant at the TMS and any configuration if different profiles are available.
- `secret` (object) — API key/credentials for to authorize the merchant
  - `digest` (string) — sha-256 digest over nonce and merchant API key. Format `sha256(nonce+key)`
  - `nonce` (string)

### Example request

```json
{
  "identifier": "merchant-12345-profile-65432",
  "secret": {
    "digest": "8C3891B3162DB3AB61A9B2DA74E6A479553ABA897894E5236ED290C11A0B832B",
    "nonce": "lRFUpqW7Xd"
  }
}
```

## Responses

### 201

Bearer token created successfully

`application/vdn.klarna.shipping.auth-v1+json`

- `token` (string) — Authorization token, will be used as bearer. Recommended implementation using JWT

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudCI6ImZvb2JhciJ9.k2tE6vdJAEGbYSeZj2YluRK5vZbPAxsjd7XqARpBX3Y"
}
```

### 400

The /auth request was malformed. In order to simplify debugging,
the field `failure_reason` should contain a text describing the failure reason.

`application/vdn.klarna.shipping.auth-v1+json`

- `failure_reason` (string)

```json
{
  "failure_reason": "'example123' is not a valid user identifier"
}
```

### 401

Invalid or missing credentials