Authentication

Every Partner API request carries a Bearer token:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Your partner identity is inside the token. You never need to tell us who you are in a request body.

Getting a key

There are two routes, and they are not equivalent.

See what your account controls for the full list of what onboarding configures.

Self-service registration

For prototyping and evaluation. Skip this if you are being onboarded; your account manager issues your credentials directly.

sequenceDiagram
    autonumber
    participant You
    participant API as Chaiz API
    participant Mail as Your inbox

    You->>API: POST /Partners/Register
    API-->>You: 200 accepted
    API->>Mail: verification code
    Mail-->>You: code
    You->>API: POST /Partners/Register/Verify
    API-->>You: 201 with your API key
    Note over You: shown once, store it now

1. Register. POST /api/v2/Partners/Register with contactEmail, displayName, and agreedToTerms: true. We email a verification code. One registration per email address. Your partner ID is made from organizationName (or displayName). If that ID is already taken, we add a suffix, so each email address gets its own partner ID.
2. Verify. POST /api/v2/Partners/Register/Verify with the code and the email field (contactEmail is accepted as an alias when email is missing or empty). The response contains your API key, partner ID, tier, and rate limits.
3. Store the key. It is shown once. Rotating a key needs the current key, so if you lose it, contact dev-support@chaiz.com.

Codes expire, and too many failed attempts invalidates the pending registration, in which case start again at step 1. Both of these calls are unauthenticated; every other endpoint is not.

If Register or Verify fails, the answer is 400 with one plain sentence (Content-Type: text/plain) that says what to fix, for example The request body is missing, is not valid JSON, or has a field of the wrong type. See Errors for the full list.

Limits

• The verification code is valid for 60 minutes from your first Register call. If you call Register again while the code is still valid, we send the same code again. The 60 minutes do not restart.
• You have 5 attempts to enter the code. The 5th wrong code cancels the registration and answers Verification failed. Please register again. Then register again to get a new code.
• In production, Register and Verify share one limit: 10 requests per hour and 50 per day, per IP address. UAT does not enforce this limit.
• Register refuses a new registration when your IP address already has 3 active keys. Only Register checks this cap. The cap is checked first, so it also refuses a Register that would only re-send a pending code. To free a slot, deactivate a key you do not use with DELETE /api/v2/Partners/Register, or contact dev-support@chaiz.com.
• One registration per email address. If you register again with an email that already has an active key, no new code is sent. The response does not say whether the email exists. After you deactivate the key, the same email can register again.

Worked example with runnable curl: Quickstart.

Environments

The old UAT address https://chaiz-api-uat.azurewebsites.net still works.

Keys are issued per environment and are not interchangeable. A UAT key against production returns 401. Register separately in each.

Calling from your servers

Production sits behind a firewall that screens automated traffic before it reaches the API. Calls from servers often look automated to it, and a call it stops gets a 403 with an HTML page instead of a JSON body. UAT does not screen traffic this way, so an integration that works on UAT can still be stopped in production.

If you call the production API from your servers, send us during onboarding either their fixed egress IP addresses or the fixed User-Agent string your client sends, and we let that traffic through. Tell us before either one changes. See Going Live.

Managing your key

All three require your current key as the Bearer token.

Rotate when a key may have been exposed, when someone with access to it leaves, or on whatever schedule your own policy requires. Enterprise credentials are rotated by your account manager rather than through this endpoint.

The optional partner field

Several request bodies accept a partner field. Leave it out. We resolve it from your token.

If you do send it, it must match your token's partner identity exactly, or the request is rejected. The field exists for older integrations and offers no benefit in new ones.

Security requirements

These are obligations under the API License and Acceptable Use Policy, not suggestions.

Keep the key server-side. Treat it as a password. A self-service key expires after 365 days (Verify and Rotate return expiresAt). Store it in environment variables or a secrets manager, never in source control, and never in anything that reaches a browser or a mobile binary. A key in client-side code is a key that has been published.

HTTPS only. Plain HTTP requests are rejected.

When authentication fails

A partner field that disagrees with your token surfaces as an authorization error, not a validation error. If a request fails with auth errors and you are sure the key is good, check whether you are sending partner.

Next steps

• Quickstart to make your first authenticated call.
• Choose Your Integration to decide what to build.
• Errors & Rate Limits for tier limits and retry behavior.

Authentication problems, tier changes, or enterprise credentials: dev-support@chaiz.com.