Authentication and API keys

Every request to asicapi is authenticated with an API key sent as a bearer token. Keys are created in the dashboard, scoped to the ASIC products and jurisdictions your account has enabled, and come in two flavours: test keys that hit the sandbox for free, and live keys that query ASIC's register and incur statutory fees. There are no session tokens or OAuth flows to manage; a key in the Authorization header is all a request needs.

Sending your key

Pass the key in the Authorization header using the Bearer scheme. All requests must use HTTPS; plain HTTP connections are refused before any key is read.

curl https://api.asicapi.dev/v1/companies/004085616 \
  -H "Authorization: Bearer asicapi_live_7Hq3nR8tW2yU5kM9pL4vX1cZ6bF0dJ"

Keep keys out of source control and client-side code. Load them from an environment variable or a secrets manager and use a distinct key per application so a leaked key can be revoked without taking down everything else.

Live and test keys

Both prefixes use the same base URL, https://api.asicapi.dev/v1, and the same paths, so switching from development to production is a matter of swapping the key. Responses from a test key always carry "meta": { "billable": false }, including purchases and orders. The sandbox page describes what the sample data looks like and lists the ACNs you can use.

Scopes and products

A key is granted access to one or more ASIC products. A product scope is only consulted on the requests that spend money: the purchase POSTs that create extracts and the order POSTs that create orders. The product names are the same strings that appear in meta.product on those responses, so you can tell from any billable response which scope it consumed.

Free lookups need no product scope. Every key can search companies and people in the ASIC jurisdiction, read a company's identity with GET /v1/companies/{id}, list documents, browse registers, validate identifiers, fetch reference data, and read any extract or order the account already holds, including through section endpoints such as GET /v1/companies/{id}/officeholders. See free lookups, extracts and orders for the full split.

Calling a purchase or order endpoint for a product the key does not have returns 403 with code product_not_enabled. Reading a section for which you hold no extract is not a permission problem; it returns 402 extract_required telling you which purchase to make.

Jurisdictions

ASIC administers companies nationally, and it also operates a bureau service that stores and serves business names and other state-registered organisations for every state and territory except Victoria. Access to each of those jurisdictions is authorised separately, and not every product is offered by every jurisdiction.

In asicapi the jurisdiction is a query parameter on the endpoints where it matters (name search, business name lookup, weekly summaries). The default is ASIC, ASIC itself, which is what almost every caller wants.

Victoria (VIC) is a valid code in the controlling jurisdictions table but Victorian business names are not served, so requests for it return product_unavailable_in_jurisdiction. Jurisdiction access is enabled per account in the dashboard; a request for a jurisdiction your account has not enabled returns product_not_enabled with the jurisdiction named in message.

{
  "error": {
    "type": "permission_error",
    "code": "product_not_enabled",
    "message": "Your account is not enabled for name_search in jurisdiction QLD (Queensland). Enable it in the dashboard or use jurisdiction ASIC.",
    "param": "jurisdiction",
    "asicCode": "ZZ02",
    "requestId": "req_01J8ZK8D3E7F1G",
    "docUrl": "https://asicapi.dev/docs/errors#product_not_enabled"
  }
}

Rotating keys

Rotate a key from the dashboard. Rotation creates a replacement key immediately and keeps the old key working for a grace period you choose (up to 72 hours) so you can deploy the new secret without downtime. Revoke the old key early once every service has picked up the replacement.

Recommended practice:

1. Create the new key and store it in your secrets manager.
2. Roll your services to read the new key.
3. Watch the dashboard's per-key request count until the old key stops receiving traffic.
4. Revoke the old key.

Revocation is instant and cannot be undone. Requests made with a revoked key return 401 with code unauthorized.

Authentication errors

A missing, malformed, revoked or expired key returns 401.

{
  "error": {
    "type": "authentication_error",
    "code": "unauthorized",
    "message": "No valid API key was provided. Send your key as Authorization: Bearer asicapi_live_... or asicapi_test_...",
    "param": null,
    "asicCode": null,
    "requestId": "req_01J8ZK9E4F8G2H",
    "docUrl": "https://asicapi.dev/docs/errors#unauthorized"
  }
}

A valid key that is not allowed to do what it asked returns 403. The three permission errors are:

{
  "error": {
    "type": "permission_error",
    "code": "sandbox_product_unavailable",
    "message": "Weekly summaries are not available with a test key. Use a live key to call /v1/weekly-summaries.",
    "param": null,
    "asicCode": "ZZ54",
    "requestId": "req_01J8ZKA0B5C9D3",
    "docUrl": "https://asicapi.dev/docs/errors#sandbox_product_unavailable"
  }
}

Related