E-invoicing · Setup & configuration · 11 min read

Onboard a provider and manage credentials

Register the company with a provider, bind credentials, rotate keys, and approve a production onboarding with a second person.

Before you begin

• A provider exists and is Active (see below). The sandbox is created for you.
• Production onboarding needs the authority's or provider's acceptance evidence, an authority-issued signing certificate and a certified production profile that passed conformance. A real production send is not certified yet in this release.
• Three duties are kept apart: the person who prepares the onboarding, the custodian who binds credentials, and the approver who activates.

Create a provider

1. Open E-invoicing > Configuration > Providers and click New.
2. Enter Code (capitals, unique), Name, Kind (Sandbox, ZATCA Fatoora or UAE accredited service provider) and Environment (Test or Production). The sandbox can only be Test.
3. Enter the Base URL. It must be HTTPS on the standard port, on a public address, without a user name or password, and its host must be on the Allowed hosts list. Addresses such as localhost or private networks are refused: "That address points at this machine or an internal network."
4. Choose Authentication (None, Bearer token, Basic or ZATCA CSID), set the Timeout (seconds) (1 to 120, default 20) and say whether the provider answers status queries and sends callbacks.
5. Save. The provider is a Draft.
6. A different person with einvoicing.activate clicks Review, then Activate. Editing after review sends it back to Draft, and the person who edited last cannot activate it.

Check health contacts the provider; use it on a Test provider first.

Create an onboarding

1. Open E-invoicing > Configuration > Onboarding and click New onboarding.
2. Choose the Provider. The environment must equal the provider's.
3. Optionally limit it to one profile.
4. Enter the Tax registration number, Provider account, Endpoint scheme and Endpoint identifier. For ZATCA, enter the Solution unit serial or let the system make one.
5. Save, then click Start testing, and Request activation.

For a Test onboarding the state goes Draft, Testing, Active without a second person, because a test onboarding cannot send a legal document. An Active onboarding cannot be edited: "An active onboarding is not edited; suspend it first."

For Production, a different person with einvoicing.activate must click Approve. The requester sees "Somebody other than the person who prepared this onboarding must approve it." Approval is refused with a message for each missing gate: acceptance evidence of at least 10 characters, a certified production profile that passed conformance, an active production authentication credential, and an active production signing key with the authority's certificate (not self-signed).

Bind a credential

1. Open the onboarding and click Bind credential. The custodian role (einvoicing.secret) is needed.
2. Choose the Purpose: Authentication, Signing key or Callback secret.
3. Enter the Token or secret, or switch on Generate it here for a signing key (an ECDSA key) or a callback secret. For a signing key you may paste the Private key and Certificate instead. The certificate must belong to the key.
4. Enter Valid to for authentication and callback credentials.
5. Save.

In Test the credential is Active at once. In Production it is Awaiting approval; a different person with einvoicing.activate approves it. The custodian is refused with "Somebody other than the person who prepared this credential must approve it." A newer credential of the same purpose marks the older one Rotated.

Secrets are shown only as a reference like "vault:a1b2c3…". A secret you entered or generated cannot be read again, so keep your own copy of anything you need elsewhere. A test credential cannot be bound to a production onboarding.

Suspend, reinstate, retire

• Suspend stops sending and shows the reason in a banner. Sending then raises a "not ready" alert.
• Reinstate needs an approver who did not request it.
• Retire is final.
• Compromised (custodian or approver) destroys the secret, suspends the onboarding, reconciles uncertain sends first and re-signs unsent documents when a new key is bound.

Check on a credential tests its health. A credential nearing its Valid to date raises an alert from the daily scan; an expired one turns Expired.

What happens next

Sending uses only an Active onboarding, an Active profile and Active credentials in the same environment. Otherwise the submission waits and an alert appears.

Good to know

• Requesting ZATCA compliance and production CSIDs (certificates) from the screen is not available yet: the buttons are unlabelled and cannot take the one-time password. Your administrator does this through the system interface.
• There is no Revoke button yet.
• Read-only lists are on Configuration > Credentials and Reports > Credential health.