Authentication
A partner system obtains an OAuth 2.0 access token from the installation's Keycloak its realm with the client_credentials grant. Send the token to an approved ITS partner route over ordinary HTTPS. Core validates its issuer and environment audience, then checks organisation, country, delegation and operation permissions.
The Environments page gives the token URL and HTTPS entry for each environment. Sandbox uses audience its-core-sandbox; Live uses its-core-live. Keep each credential with its matching entry. NGINX requires no partner client certificate or trust bundle. Keep normal HTTPS server-certificate validation enabled. Paths below are relative to ITS_PARTNER_URL, whose value ends in /api/v1.
| Variable | Meaning |
|---|---|
ITS_TOKEN_URL | The selected installation's token endpoint. |
ITS_PARTNER_URL | The selected environment's HTTPS partner entry plus /api/v1. |
ITS_CLIENT_ID and ITS_CLIENT_SECRET | The selected environment's machine credential. |
ITS_TOKEN | Short-lived access token held in memory. |
Request a token:
curl --fail-with-body --silent --show-error \
--user "$ITS_CLIENT_ID:$ITS_CLIENT_SECRET" \
--data 'grant_type=client_credentials' \
"$ITS_TOKEN_URL"
Use the returned access_token and expires_in. Renew before expiry by repeating the grant; client credentials do not provide a refresh token. Make a Sandbox read:
curl --fail-with-body --silent --show-error \
--header "Authorization: Bearer $ITS_TOKEN" \
--header 'Accept: application/json' \
"$ITS_PARTNER_URL/etd?page-number=1&page-size=1"
What a partner credential may do
The Portal issues every partner credential, Sandbox and Live, with the same three roles, plus one access role for its environment:
| Role | What it grants on the partner entry |
|---|---|
| Customs officer | Read declarations (etd:read), lodge (etd:issue), amend (etd:amend), stamp (etd:endorse) and attach documents (etd:attach) |
| Departure authority | Read, amend and cancel (etd:cancel) |
| Partner system | Read, and acknowledge announcements (etd:acknowledge) |
its-core-sandbox-access or its-core-live-access | Admits the token to that environment only (audience its-core-sandbox or its-core-live) |
The set is fixed by ITS, not chosen per partner, and no credential is issued unless every role exists. A Sandbox credential never works on Live, or the reverse.
Holding a permission is not enough on its own. Core identifies your organisation from the credential and checks each operation's permission and country scope. A REC may act only for countries that delegated to it. A successful token request alone does not prove that a particular operation is allowed. Keep normal HTTPS server verification enabled.
When a call is refused
If a call is refused, first confirm the Authorization header is present and the token has not expired. Then check its issuer, audience and matching environment. For a 403 with a valid token, check the organisation's admission, participation or delegation and the operation permission. Keep the response's correlation ID for troubleshooting. Never log or send the client secret or token to support.