> **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:

1. 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.
2. Open **Account, API Keys** and create or copy an API key and secret.
3. 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:

1. Stop. Do not try to guess keys or find a sign-up endpoint.
2. Record that you needed access and could not get it, and which task needed it.
3. 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](https://addrexy.com/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.

## Next

Calling the APIs: [/agent/build](https://addrexy.com/agent/build).