# Get an authorization token

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 .

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.

Endpoint: POST /auth
Version: 1.3.0

## Request fields (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.
    Example: "merchant-12345-profile-65432"

  - `secret` (object)
    API key/credentials for to authorize the merchant

  - `secret.digest` (string)
    sha-256 digest over nonce and merchant API key. Format sha256(nonce+key)
    Example: "8C3891B3162DB3AB61A9B2DA74E6A479553ABA897894E5236ED290C11A0B832B"

  - `secret.nonce` (string)
    Example: "lRFUpqW7Xd"

## Response 201 fields (application/vdn.klarna.shipping.auth-v1+json):

  - `token` (string)
    Authorization token, will be used as bearer. Recommended implementation using JWT
    Example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudCI6ImZvb2JhciJ9.k2tE6vdJAEGbYSeZj2YluRK5vZbPAxsjd7XqARpBX3Y"

## Response 400 fields (application/vdn.klarna.shipping.auth-v1+json):

  - `failure_reason` (string)
    Example: "'example123' is not a valid user identifier"


## Response 401 fields