Authentication

The Customer API uses the OAuth 2.0 client credentials grant. You exchange your Customer Code and API Key for a short-lived JSON Web Token (JWT), then send that token in the Authorization header on every subsequent request.

This is a standard machine-to-machine authentication flow supported by all major HTTP libraries — you usually don't need to implement it by hand.

Credentials

To use the API you need two values, issued by Kiss when you sign up:

Credential	Used as	Example
Customer Code	The OAuth client_id	ACME01
API Key	The OAuth client_secret	a long random string

Treat the API Key like a password. It grants full read access to your customer-scoped data. Do not commit it to source control, do not share it in chat messages, and rotate it immediately if you suspect it has been exposed (see Key rotation).

The token endpoint

POST /auth/token

Exchange a Customer Code and API Key for a short-lived access token. This endpoint does not require authentication itself.

Request

The request body is application/x-www-form-urlencoded — the same content type used by standard OAuth implementations.

Parameter	Required	Description
grant_type	Yes	Must be client_credentials.
client_id	Yes	Your Customer Code.
client_secret	Yes	Your API Key.

Example

POST /auth/token HTTP/1.1
Host: api.kiss.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=ACME01&client_secret=YOUR_API_KEY

Successful response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Field	Description
access_token	The JWT to send with subsequent requests.
token_type	Always Bearer.
expires_in	Token lifetime in seconds (currently 3600 — one hour).

Error responses

The token endpoint follows the standard OAuth 2.0 error format:

{ "error": "invalid_client", "error_description": "Invalid client credentials." }

Status	error value	Cause
400	unsupported_grant_type	grant_type was not client_credentials.
400	invalid_request	client_id or client_secret is missing.
401	invalid_client	The Customer Code is unknown, the API Key is wrong, the key has expired, or the customer account is disabled.

Using the access token

Send the token in the Authorization header of every request to a protected endpoint:

GET /products HTTP/1.1
Host: api.kiss.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Any of the standard ways of setting headers in your HTTP client will work — there is nothing API-specific about how the token is sent.

A missing, malformed, or expired token returns 401 Unauthorized.

Token lifetime and renewal

• Tokens expire after 3600 seconds (one hour).
• The token is not automatically refreshed — when it expires, the next request returns 401 Unauthorized, and your client must request a new token from /auth/token.
• The best practice is to cache the token in memory and request a new one a few minutes before it expires (for example, when the current time is within five minutes of the expiry).
• There is no token revocation. Once issued, a token remains valid for its full lifetime even if the underlying API key is revoked or the customer account is disabled. Revocation only takes effect at the next token request.

Key rotation

API keys have an expiry date (default: one year after issue). To rotate a key:

1. Ask your Kiss account manager to issue a new API Key.
2. Update your application's configuration with the new key.
3. Verify your application can authenticate using the new key.
4. Ask your account manager to revoke the old key.

There is currently no self-service key rotation portal. If you suspect your key has been compromised, contact support@kissmecostumes.com immediately and we will issue a new key and revoke the old one.

Security checklist

• Store your API Key securely (e.g. in a secrets manager, never in source control).
• Always use the HTTPS URL provided by Kiss. The deployment is reachable over HTTPS through a TLS-terminating proxy; sending credentials over a plain-HTTP URL would expose them in transit.
• Treat the access token as sensitive — anyone with the token can read your data until it expires.
• Rotate keys on a regular schedule and immediately if you suspect compromise.
• Restrict access to the API Key to the smallest possible number of people and systems.