Draft: Addrexy is not live yet. It will run at https://addrexy.com as a tenant of the white-label developer portal. In version 1 the portal and its documentation are those of the existing white-label tenant at https://intodq2.devapicloud.com; the API and the documentation are the same. TBD marks something not yet decided. Not documented marks something the white-label documentation does not say.

Start: get access

How access works

Addrexy runs on a white-label developer portal. In that portal:

A partner administrator manages users and credits.
Users sit in three levels: Administrator, Customer, Department. Credits are allocated down the tree.
Each department has its own API key and secret.
A person retrieves the key and secret in the portal under Account, API Keys.

An agent cannot create an account or a key. There is no documented sign-up call, no anonymous access, and no way for an agent to buy credits. Whether any of that will exist is TBD.

If you are helping a developer

Ask your human to:

Sign in to the portal (version 1: https://intodq2.devapicloud.com; later https://addrexy.com). TBD: how an account is created; the administrator may need to create it. The portal's documentation is at https://intodq2.devapicloud.com/assets/developer-portal.html.
Open Account, API Keys and create or copy an API key and secret.
Give you the key and secret through a secret store or environment variables. Do not accept them pasted into a file that is committed to source control.

Then store them as environment variables, for example ADDREXY_API_KEY and ADDREXY_API_SECRET, and read them on the server only.

If you are an independent agent with no human

You cannot get access today. Do this:

Stop. Do not try to guess keys or find a sign-up endpoint.
Record that you needed access and could not get it, and which task needed it.
Report it to whoever configured you, or, if nobody did, write it to your output or log. The administrator must create a user and allocate credits.

Authenticate

Every call uses HTTP Basic authentication. Build the header from the key and secret:

Authorization: Basic base64(ApiKey:ApiSecret)

Also required on every call:

Content-Type: application/json
X-Session-Token: <a UUID v4>

Create the session token with crypto.randomUUID() (JavaScript), uuid.uuid4() (Python) or uuidgen. For autocomplete, create one when the address field gets focus and reuse it for that whole search session. For verify, create one per verification flow. The documentation gives no rule for geocode; Addrexy guidance is one per request or per flow. Optionally send X-Request-Id (alphanumeric, hyphens, underscores, up to 38 characters) so you can correlate calls. It is echoed on the response and generated if you omit it. The session token groups calls for billing and audit.

Make a first call

POST https://api.devapicloud.com/v1/address/verify
Authorization: Basic <base64 of key:secret>
Content-Type: application/json
X-Session-Token: 550e8400-e29b-41d4-a716-446655440000

{ "query": { "address": "20 W 34th St, New York NY 10118", "countryCode": "USA" } }

A good response is 200 with result.status of OK and a result.matchScore. If you get 401, the key or secret is wrong or missing. If you get 403 SUBSCRIPTION_INACTIVE, stop and tell your human. See /agent/operate.

Credits and countries

Calls draw down credits allocated to your department. Cost per call is not documented. What happens when credits run out is not documented: expect an error, and do not retry in a loop. Whether a failed or retried call uses credits is also not documented.
Your subscription decides which countries work. A valid country that is not covered returns UNSUPPORTED_COUNTRY. Ask the administrator to add it.
A key has a scope per API. The documentation names an Address Autocomplete scope, an Address Verification scope and a Geocoding scope. A key without the scope for an API returns FORBIDDEN. Whether forward and reverse geocode share one scope is implied (both say "Geocoding API scope") but not stated.

Calling the APIs: /agent/build.