API Authentication and Bearer Tokens

How Authentication Works

1. Register and log in to your Quote3D account.
2. Generate an API token from your dashboard under the "Tokens" tab.
3. Include the token in your API requests. Authorization: Bearer is supported, and X-API-Token is also accepted:
   Authorization: Bearer YOUR_TOKEN_HERE
4. The server verifies your token and grants access if it is valid and unexpired.

Token Scopes

A token's scope decides which endpoints it can reach. You choose the scope when you create the token, and you can see it on the Tokens page of your dashboard.

• Full access — the default for a server-side token. It reaches every endpoint your plan allows.
• Widget — the scope to use for a token you embed in a storefront. It is limited to what the embeddable widget needs, and cannot reach webhooks, account details, analytics, usage, or quota.

A call to an endpoint outside the token's scope is rejected with 403 even though the token itself is valid. If a request fails with 403 while the same token works elsewhere, check its scope before anything else.

Token Lifecycle

• A token's value is shown once, at creation. It is not recoverable afterwards — store it in your secret manager immediately. If you lose it, rotate the token to get a new value.
• Tokens may be created with an expiry. An expired token stops working and returns 401; the dashboard shows each token's expiry date.
• Rotating a token issues a new value and invalidates the old one straight away. Deploy the new value before rotating, because in-flight requests using the old token begin failing immediately.
• A token can be restricted to a list of IP addresses. Calls from any other address are rejected with 403 — a common surprise after moving a server or changing a NAT gateway.
• Your plan limits how many tokens you can hold. Free plans allow one server token and one widget token.

When Authentication Fails

A rejected request returns the standard error envelope with success: false and a short message. Branch on the HTTP status code rather than the message text, which may be reworded.

{
  "success": false,
  "error": "API token has expired"
}

• 401 — the token is missing, malformed, expired, or revoked. Check the header name and that the value was not truncated when it was copied.
• 403 — the token is valid but not permitted for this call. The usual causes are a scope restriction or an IP allowlist that does not include the caller.

Token Format

Quote3D tokens are bearer-style API credentials. Clients should treat them as opaque secrets and avoid depending on the token's internal structure.

A JWT consists of three parts:

1. Header: Specifies the signing algorithm and token type.
2. Payload: Contains user data and claims (like user ID, email, and expiration time).
3. Signature: Verifies that the token has not been tampered with.

A token may look like this:

For integrations, the important rule is simple: store the token securely, send it on each request, and avoid parsing or exposing it in client code unless the integration explicitly requires a client-side token.

Example: Using Your Token

Here is how you might use your token with curl. Use one authentication header style consistently:

Or in the API playground, paste your token into the authorization modal (lock icon) to authenticate your session. You can also use X-API-Token in custom integrations if that header fits better.