Authentication and Authorization

This guide explains how an integration proves who it is and what it may do: the API key the Company issues to your account, the scope and tier that bound it, and the rules for storing, using, rotating, and retiring it. Authentication and authorization for the API are one subject, because the key carries both: it identifies your account, and everything it may read or change follows from that identity. Endpoint detail is in Authentication Endpoints; the governing instruments are the Developer Agreement and the API Access Tiers.

The model in one paragraph

The Company issues one or more API keys per account. A key is presented on every request as a bearer token, identifies exactly one account, and works only within the permissions of that account's access tier. There is no anonymous API access, no shared key across accounts, and no way for a client to widen what a key can do: a request either falls inside the key's account and tier, or it is rejected. API access is limited by seller type: manufacturer and supplier accounts receive API access for importing data.

Presenting the key

Every request carries the key in the Authorization header

Authorization: Bearer <your-api-key>

• Requests without a valid key are rejected with 401.
• A key works only over HTTPS at the base URL https://www.aapawz.com/api. Do not send a key to any other host.
• The key is a secret from the moment it is issued. It is shown once; store it at that moment, because the Company does not display it again.

What a key may do: account, scope, and tier

Three bounds apply to every call, and all three must permit it

1. Account. The key reaches only its own account's resources. There is no parameter, header, or id that extends a call into another account; an id from another account simply does not resolve.
2. Scope. At issuance, the key is granted the resource domains the integration declared: for example catalog reads, or catalog and inventory writes. A call outside the granted domains is rejected with 403.
3. Tier. The API Access Tiers set what an account type may do with the API at all, including volumes and which operations are available. Your tier is set by the Company; if your integration outgrows it, request a change rather than engineering around it.

When you request a key, declare your intent precisely: what you are building, which domains you need, and what data the integration will import: and request broader scope when your needs grow. Working around a scope you were not granted is a policy violation, covered in API Policies.

Storing and handling keys

• Store keys in a secrets manager, injected into your server environment at deploy time.
• Never place a key in source control, in a client application, in a mobile app, in a browser, in a log line, or in a support ticket.
• Use keys only from server-side systems you control. Any person or system that can read the key can act as your account.
• Name each key by purpose inside your own records: for example, which system uses it and what for: so usage can be audited and a single key can be retired without hunting for it.
• If you run separate environments (development, staging, production), hold separate keys for each, and never let a test system call the API with a production key against live account data.

Rotation and revocation

Rotate keys on a schedule and immediately on suspicion: a departed employee who knew the value, a log that captured it, a machine that was compromised. Rotation and revocation mechanics, including any overlap window, are specified in Authentication Endpoints and the API Key Management and Rotation Policy. The working rules

1. Issue or request the replacement key before retiring the old one, where the flow allows overlap.
2. Deploy the replacement, confirm calls succeed, then retire the old key.
3. Revoke first and investigate second when a key may be exposed. A revoked key can be replaced; an exposed key that stays live cannot be un-used.
4. When a person leaves your team, review every key they could read.

Acting for another account

Where the Company has authorized your integration to act for another account: for example, a provider serving several sellers: each relationship is authorized separately, and each account's data is reached only under the authorization granted for that account. Never use one account's authorization to reach another account's data, and end access promptly when a relationship ends. Solution Providers states the obligations in full; Security and Compliance states the custody rules.

Failure handling

• 401: no valid key was presented. Check, in order: the header is present and correctly formed; the stored value has not been altered in copying (a single changed character is the most common cause); the key has not been revoked or rotated out. Do not retry in a loop.
• 403: the key is valid but the call is outside its account, scope, or tier. Fix the request or request the scope; repeated probing after a 403 is treated as misuse.
• A key that suddenly reads or writes at unusual hours or volumes is an anomaly worth an alert on your side. Log key usage by purpose so anomalies surface.

Checklist

• Key stored in a secrets manager; shown-once value captured at issuance.
• Key used only server-side, only over HTTPS, only at the Platform base URL.
• Scopes match the declared integration; broader needs requested, not worked around.
• Rotation scheduled; revocation rehearsed; leavers' access reviewed.

Questions about credentials issued to your account: support@aapawz.com.