Skip to content
Docs
Get playground access
POST

Get an authorization token

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 body4 fields
  • identifierstringoptional

    Handled as a string. Should uniquely identify the merchant at the TMS and any configuration if different profiles are available.

  • secretobjectoptional

    API key/credentials for to authorize the merchant

    2 fields in secret
    • digeststringoptional

      sha-256 digest over nonce and merchant API key. Format sha256(nonce+key)

    • noncestringoptional
201
Response1 field

Bearer token created successfully

  • tokenstringoptional

    Authorization token, will be used as bearer. Recommended implementation using JWT

400
Response1 field

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

  • failure_reasonstringoptional
401
Response0 fields

Invalid or missing credentials

No response body — this status returns headers only.

This page is also available as Markdown — append .md to its URL — and is indexed in llms.txt.