Authentication

AECloud uses OAuth2 with the client-credentials grant for system-to-system integration. The client represents the merchant integration to AECloud, not an interactive end user and not AECloud's intermediary identity at MyInvois.

Two authentication layers

  1. The downstream system exchanges its merchant AECloud client ID and secret for an AECloud access token.
  2. When an authorized document is processed, AECloud separately authenticates to MyInvois as an intermediary acting on behalf of the taxpayer.

Do not send MyInvois credentials to an AECloud document endpoint or place any client secret in a business payload.

Obtain credentials

An authorized merchant user can view or generate the API client from the Merchant Console's Merchant area under API Client. An authorized reseller or AECloud administrator may also manage a merchant credential as part of an approved support process.

Record the client ID and secret directly into the destination secret store. Do not put either value in public documentation, screenshots, source control, sample payloads, support tickets, or application logs.

Request an access token

Send a form-encoded POST request to the environment's token URL:

curl --request POST "{token_url}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id={client_id}" \
  --data-urlencode "client_secret={client_secret}"

Read access_token from the JSON response. Also read expires_in when returned and cache the token until shortly before expiry.

Do not request a new token for every document. Reuse the valid token and refresh it only when required.

Authorize API calls

Send the token in the Authorization header:

Authorization: Bearer {access_token}

JSON POST requests also require:

Content-Type: application/json
Accept: application/json

Token-handling pattern

  1. Look for a non-expired token in the application's secure token cache.
  2. If none exists, acquire a lock so concurrent workers do not request separate tokens.
  3. Request and securely cache a token.
  4. Call the API with the bearer token.
  5. On an authentication failure, invalidate the cached token and retry token acquisition once.
  6. If authentication still fails, stop and alert; do not loop continuously.

Credential regeneration

Generating a replacement API credential invalidates the previous client. Coordinate rotation across every connected POS, ERP, outlet, service, and background job.

A safe rotation procedure is:

  1. inventory every consumer of the current credential;
  2. schedule a controlled change window;
  3. generate the replacement;
  4. update all secret stores;
  5. request a new token and test GET /version/;
  6. test a permitted sandbox operation or production health check; and
  7. monitor authentication failures after the change.