Authentication

To access protected endpoints:

Send a request to the appropriate authentication endpoint.

Exchange your credentials for a JWT.

Include the JWT in the Authorization header of all subsequent API requests.

The JWT represents your authenticated session and must be handled securely. Depending on the authenticated role (multiplier, customer, voucher owner, or API key access), access to certain endpoints or resources may be restricted.

JSON Web Token (JWT)

A JWT is a compact, URL-safe token with the following structure:

Introduction to JSON Web Tokens

For debugging purposes, JWTs can be decoded using tools such as jwt.io.
Decoding a token does not validate its signature or permissions.

<encoded header>.<encoded payload>.<encoded signature>

Each part is Base64-encoded and serves a specific purpose:

Header
Contains metadata about the token, such as the token type and signing algorithm.

Payload
Contains claims describing the authenticated entity and access scope, for example:

subject identifier (sub)

expiration timestamp (exp)

audience (aud)

Signature
Ensures the integrity of the token and prevents tampering.

Example (Decoded Token)

header = {
  "typ": "JWT",
  "alg": "HS256"
}

payload = {
  "sub": "58e262c93aaf3b3fdf47691f", // entity id
  "exp": 1519642499, // expiration date 
  "aud": "api_access" // entity type (multiplier, customer, voucher_owner or api_access)
}

Token Security

Treat JWTs like passwords.

Do not share or expose tokens publicly.

Always transmit tokens over HTTPS.

Store tokens securely and rotate them if compromised.

Token Expiration

JWTs are issued with a limited lifetime, defined by the exp claim.

Once a token has expired, it can no longer be used and a new token must be obtained
by authenticating again.

Clients should always be prepared to handle 401 Unauthorized responses.

Rate Limits

To ensure platform stability and fair usage for all consumers, the Givve-API enforces rate limits on incoming requests. These limits help protect the API from misuse and ensure consistent performance.

Rate Limit Enforcement

When a rate limit is exceeded, the API responds with the HTTP status code:

The response body contains an error message indicating that the request rate has been exceeded. The format of the error response depends on the requested Content-Type.

Rate Limit Headers

Every API response includes headers that provide information about the current rate limit status:

X-RateLimit-Limit
The maximum number of requests allowed for the current endpoint within a defined time window.

X-RateLimit-Remaining
The number of requests remaining in the current time window.

X-RateLimit-Reset
A UNIX timestamp indicating when the rate limit window resets and the request counter is refreshed.

If a request is rejected due to rate limiting, the response also includes:

Retry-After
The number of seconds a client must wait before retrying requests to the same endpoint.

Rate Limit Thresholds

As a general guideline, clients should expect a limit of approximately 300 requests per 5-minute window.

Rate limits may vary depending on the endpoint and are not part of the stable API contract. Givve reserves the right to adjust limits, including applying dynamic limits, to maintain overall service reliability.

Client Responsibilities

Clients are expected to:

Monitor rate limit headers on every response.

Implement backoff or retry logic when receiving 429 Too Many Requests.

Avoid burst traffic that exceeds documented thresholds.

Failure to respect rate limits may result in temporary request blocking.

Overview

Authentication#

JSON Web Token (JWT)#

Example (Decoded Token)#

Token Security#

Token Expiration#

Rate Limits#

Rate Limit Enforcement#

Rate Limit Headers#

Rate Limit Thresholds#

Client Responsibilities#