Authentication

The Giftronaut API uses OAuth 2.0. All requests to /api/v1/** require a valid Bearer token in the Authorization header.

Regardless of whether you call the REST API or MCP, Giftronaut uses OAuth bearer authentication, where each request must include your access token. The value of the Authorization header is the string Bearer, followed by a single space, followed by your OAuth access token.

Client Credentials flow

OAuth 2.0 Client Credentials is a server-to-server authentication method using a client_id and client_secret. It requires no user interaction and is best suited for server-to-server integrations.

Ideal for server-to-server integrations where no user interaction is required.

1. Create a sandbox app

Log in to the developer portal, navigate to Apps, and click New app. Copy your client_id and client_secret — the secret is shown only once.

2. Request an access token

POST https://api.giftronaut.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&scope=orders.read+orders.write

3. Token response

{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "orders.read orders.write"
}

4. Use the token

GET /api/v1/orders
Authorization: Bearer eyJhbGci...

Authorization Code + PKCE flow

Use this flow when your app acts on behalf of a logged-in Giftronaut portal user.

Redirect user to /oauth2/authorize with code_challenge (PKCE)
User authenticates via the portal login page
Authorization server redirects back to your redirect_uri with code
Exchange code + code_verifier for tokens at /oauth2/token

Try It — testing in the browser

Giftronaut Try It panel

The API Reference has a built-in Try It panel that lets you send live API requests directly from your browser — no curl or Postman needed.

How to set up authentication

Sign in to the developer portal.
Navigate to any API Reference page (e.g. Orders).
Click the Set up auth button in the top navigation bar.
Select an Environment (Sandbox or Production) and a Credential.
Click Generate Token — a short-lived JWT is minted server-side and stored in your browser session.
Select any endpoint on the left. The Try It panel shows the resolved URL and an active auth state.
Click Send request to execute the call and see the live response.

The token is stored in sessionStorage — it is automatically cleared when you close the tab or log out. You can also clear it manually via the Clear button in the auth panel. No credentials ever leave the server.

Token expiry & rotation

Environment	Access token TTL
Sandbox	24 hours
Production	1 hour

Tokens cannot be refreshed via refresh_token in the Client Credentials flow — simply request a new token when it expires.