How to retrieve your FIRS credentials
FIRS/NRS issues each registered business its own e-invoicing credentials. We submit under yours, never under ours, so at some point we have to hold them. This page lists the exact fields we need, shows where each one sits in the FIRS/NRS portal, and explains when we ask for them and what happens once you hand them over.
FIRS/NRS runs a demo (test/sandbox) environment and a production environment, and issues a separate credential set for each. The two are not interchangeable. Retrieve them the same way, keep them apart, and give us the set that matches the environment you are submitting to. Demo credentials are only ever used against the demo environment.
1 · When we ask for them #
Not at registration. You can register, be provisioned, connect your system and push data with no FIRS credentials on file at all. Nothing about onboarding is blocked by them.
We ask just-in-time — at the moment a FIRS submission is first attempted, and only for the environment being attempted:
- A demo submission is attempted, so we ask for your demo credentials.
- A production submission is attempted, so we ask for your production credentials.
Any of these four actions is a first attempt and triggers the request:
| Trigger | What happens |
|---|---|
| You turn submissions on for an environment | The dashboard asks for that environment's credentials before the switch takes effect |
| You click Submit on an invoice row | A dialog collects the credentials, validates them, then the submission proceeds |
| Any action that needs a live connection to a FIRS environment | Same dialog, same validation |
| An API call that asks for a submission | The call returns a plain error saying the credentials are not yet on file, and names the endpoint that stores them |
You do not have to wait to be asked. You can fill them in and have them validated at any time — from your dashboard or by API (§5). Doing it in advance means the first submission goes through without an interruption.
2 · The exact fields we need #
Six values, per environment. Collect all six before you start; a partial set cannot be validated, and we store nothing until validation passes.
| Field | What it is | Shape |
|---|---|---|
entity_id |
Identifies your organisation's account in the FIRS/NRS e-invoicing system | Identifier string, as shown in the portal |
business_id |
Identifies the specific registered business that issues the invoices. One entity can hold several | UUID, e.g.
b1d2c3e4-5678-90ab-cdef-1234567890ab |
service_id |
Your FIRS/NRS service identifier. It is a component of every IRN we mint, so it has to be exact | 1–12 alphanumeric characters, e.g. A1B2C3D4. Upper-cased on
save |
api_key |
Identifies your business on calls to FIRS/NRS | Opaque string from the portal |
api_secret |
Signs those calls. Treat it as a password | Opaque string from the portal |
public key +
certificate |
The cryptographic pair FIRS/NRS issues your business. The public key encrypts the QR payload; the certificate is embedded with it (§4) | Usually one downloaded JSON file holding both |
There is no private-key field anywhere in this flow, on any page or endpoint. The QR payload is encrypted with the FIRS/NRS-issued public key and carries your certificate; nothing needs a private key. If any form appears to ask you for one, stop and contact [email protected].
Depending on what your portal returns when we authenticate, we may also ask for your registered business name, TIN, address (including postal code) and a contact email. Where FIRS/NRS gives us those on authentication we take them from there and do not ask you twice. Have them to hand either way — a business-to-business invoice with no postal code is rejected by FIRS/NRS.
3 · Where to find each field in the portal #
Sign in to the FIRS/NRS e-invoicing portal as a user with administrator rights on the business. Read-only users can usually see the identifiers but not reveal or regenerate the secret.
The screen captures below have not been added yet. Each slot names the exact screen it will show, so the written steps stand on their own until the images land. Follow the text; treat the figures as confirmation once they appear.
-
Sign in and pick the right environment
The demo and production portals are separate sign-ins. Confirm which one you are in before you copy anything — the two credential sets look identical and are not interchangeable. Use the demo portal for demo credentials.
Figure 1FIRS/NRS portal — sign-in screen with the environment indicator (screenshot to be added)Figure 1 — FIRS/NRS portal, sign-in screen. Shows where the environment (demo or production) is indicated. Redact the account email. -
Read the entity id and business id
Open your organisation profile. The entity id is on the account or organisation record. Then open the business you invoice under — its business id is on that business's own record, usually shown as a UUID with a copy control beside it. If your organisation holds more than one registered business, take the id of the one whose invoices we will be submitting.
Figure 2FIRS/NRS portal — organisation profile showing the entity id (screenshot to be added)Figure 2 — Organisation profile. Shows the entity id and its copy control. Redact the identifier value itself, the TIN and the account email. Figure 3FIRS/NRS portal — business record showing the business id and service id (screenshot to be added)Figure 3 — Business record. Shows the business id (UUID) and the service id on the same screen. Redact both values and the TIN. -
Read the service id
The service id sits with the business record, alongside the business id. It is short — 1 to 12 alphanumeric characters. Copy it exactly: it becomes part of every IRN, so a transcription slip produces IRNs FIRS/NRS does not recognise. We upper-case it on save and reject anything longer than 12 characters or non-alphanumeric rather than trimming it silently.
-
Create or reveal the API key and secret
Go to the API access area of the portal — the section that lists integration or API credentials for the business. Either read an existing pair, or create a new one. The API secret is normally shown once, at the moment it is created, and cannot be read back afterwards. Copy it then. If it was lost, generate a replacement rather than guessing; be aware that regenerating invalidates the previous secret, so anything already using it stops working.
Figure 4FIRS/NRS portal — API access area listing the API key, with the secret shown once on creation (screenshot to be added)Figure 4 — API access area. Shows where the API key is listed and where the secret appears on creation. Redact the key and the secret in full. -
Download the cryptographic key file
In the same area, or under a separate cryptographic-keys or certificate heading, download the key file FIRS/NRS issues your business. Save it as it comes — do not open and re-save it, and do not reformat it (§4).
Figure 5FIRS/NRS portal — cryptographic keys section with the download control (screenshot to be added)Figure 5 — Cryptographic keys section. Shows the download control for the key file. Redact any visible key material. -
Note the registered business details
While you are in the business record, note the registered business name, TIN and full address including postal code, exactly as FIRS/NRS holds them. If our authentication does not return these, we will ask for them, and they must match the portal. Never send a placeholder or guessed TIN — leave it out and supply it once you have the real one.
Figure 6FIRS/NRS portal — registered business details: name, TIN, address and postal code (screenshot to be added)Figure 6 — Registered business details. Shows name, TIN, address and postal code as held by FIRS/NRS. Redact the TIN and street address.
4 · The cryptographic key file #
FIRS/NRS issues the two crypto values as a single JSON file. Paste it in exactly as it came — the whole file,
in one box. We read public_key and certificate out of it ourselves.
{
"public_key": "…",
"certificate": "…"
}- Do not re-key it by hand. The values are long; a single wrong character fails validation with no useful clue as to where.
- Do not strip or add line breaks, and do not open it in a word processor. Copy the raw file contents.
- There is one box, not two. Paste the whole file. You do not have to split it into separate fields.
- Keep the demo and production files apart. They have identical filenames often enough to catch people out.
5 · Three ways to supply them #
- When we ask. At the first submission attempt for an environment, a dialog collects that environment's set, validates it against FIRS/NRS on the spot, and continues where you left off if it passes.
- From the dashboard, whenever you like. You do not have to wait for the prompt. Enter and validate a set in advance, and the first submission runs uninterrupted. The hosted credentials setup page does the same job for the demo environment.
- By API. There is an update-merchant call for exactly this, so an integration with no interface can supply and re-supply credentials in code. The same endpoint takes demo and production sets — there is not a second one. When credentials are missing, the error we return on a submission call names it, so you can find it without reading this page first. Aggregators use the merchant-update call on their own plane; see the Aggregator guide. Field-level bodies are in the API reference.
All three paths validate identically. Whichever you use, the result is the same: accepted and stored, or rejected and nothing kept.
6 · Validation and storage #
- Validated as collected. We authenticate against the FIRS/NRS environment the set belongs to, while you wait. You get an accepted or rejected answer on the spot, not a "saved" message that turns out to be wrong days later.
- Nothing is stored on failure. A rejected set is discarded whole. You are never left half configured, and a half-configured tenant is not a state we can reach.
- Stored encrypted, per environment. An accepted set goes straight into a vault, held separately for demo and production, and is used only to sign outbound calls to FIRS/NRS on your behalf.
- Never readable again. Secrets are not echoed in any response, not written to logs, and not shown back to you in the dashboard. You can replace a set at any time; you cannot read one back. Our validation errors name which field is missing or wrong, never its value.
- Replaceable at any time. If FIRS/NRS regenerates your secret, supply the new set the same way. The new one replaces the old outright.
7 · /ingest vs /submit #
These two calls now mean different things, and the difference decides whether a missing credential is an error.
| Call | What you are asking for | Errors if credentials are missing? |
|---|---|---|
/submit |
"Submit this invoice to FIRS." An explicit instruction to fiscalize | Yes — a plain error saying the credentials are not on file, naming the endpoint that stores them |
/ingest |
"I am not forcing a submission. I want my data on the dashboard" | No — never errors for this reason |
Once your tenant is fully live for an environment, ingestion implies fiscalization. When all three of these are true —
- your data is mapped,
- demo submissions are on, and
- your demo credentials have been supplied and validated,
— then both /ingest and /submit submit to FIRS. There is no
longer a way to push a record into a fully live tenant and have it sit unsubmitted. If you want records
stored without being fiscalized, do that before the tenant is live for that environment, or keep submissions
off.
Until the tenant is in that state, the split holds: /ingest stores and shows,
/submit files.
8 · Common rejections #
| What you see | Usual cause | Fix |
|---|---|---|
| FIRS/NRS rejected the supplied credentials | Production credentials entered against the demo environment, or the reverse; or a stale secret that has since been regenerated in the portal | Confirm which portal the set came from. Regenerate in the portal and re-enter |
| A required field is missing | A partial set. All six values are needed together | The error names the missing fields. Supply them and resubmit the set |
| The service id was rejected | Longer than 12 characters, or contains a space, dash or punctuation | Re-read it from the business record. We reject rather than truncate, on purpose — a truncated service id produces wrong IRNs |
| The key file was rejected | Re-typed by hand, re-saved by an editor, or only part of the file pasted | Paste the raw file again, whole and unedited |
| A submission call says credentials are not on file | Credentials exist for one environment but not the one being submitted to | Supply the set for that environment. The error names the endpoint that stores it |
If a set is rejected and the portal shows it as valid, send us the trace_id from the response.
Do not send the credential values by email.
9 · Checklist #
- Confirmed which environment you are retrieving for, and signed in to that portal.
- Copied the entity id, business id and service id from the organisation and business records.
- Created or revealed the API key and copied the API secret at the moment it was shown.
- Downloaded the cryptographic key file unedited, and kept demo and production files apart.
- Noted the registered business name, TIN and address including postal code, exactly as held by FIRS/NRS.
- Supplied the set and seen it accepted — not saved-and-unverified.
- Understood that
/submiterrors without credentials,/ingestdoes not, and that once the tenant is live for an environment both submit. - Never entered a private key anywhere, and never sent credential values over email.