العربية

How to get your JoFotara integration credentials (Client ID and Secret Key)

By CS-Aspirations · Updated

A focused walkthrough of the JoFotara Connect Devices screen: what you need before you start, how to generate the Client ID and Secret Key, which income source sequence to choose, and what the common credential errors mean.

To send invoices from your own software to Jordan's national e-invoicing system, JoFotara needs to know who is sending them. That identity is a pair of values you generate yourself on the JoFotara portal: a Client ID (the portal calls it the user number) and a Secret Key. Together with your income source sequence, they are all your accounting or POS system needs to connect. This guide covers only that step, in more depth than our complete JoFotara guide: what to prepare, which screen to use, which choices matter and how to read the errors you may see on day one. If you want to see where these values go inside an ERP, our page on JoFotara integration in Aspirations shows the settings screen.

Before you start: three prerequisites

  1. An active tax number registered for ISTD e-services. The portal user guide published on portal.jofotara.gov.jo says the taxpayer must hold an active tax number and be registered on ISTD's electronic services before entering the invoicing system.
  2. A JoFotara account. From ISTD's e-services you follow the "national invoicing" link and create the main (Admin) user of the invoicing system with a username and password. You then log in at portal.jofotara.gov.jo with three values: the tax number, the username and the password.
  3. The Admin user. According to the portal user guide, linking devices is done from the Admin account. Sub-users, which the Admin creates for each income source sequence or branch, issue invoices on the portal but are not the ones who link software.

If your company has not joined the system yet, ISTD's technical guide points you to the joining procedures manual on istd.gov.jo first. Credentials cannot be generated for an account that does not exist.

Step by step: generating the Client ID and Secret Key

ISTD's linking procedure manual and its technical integration guide (version 1.5, published in 2026) describe the same short path:

  1. Log in to the national invoicing system with the tax number, username and password.
  2. On the home screen, open Linking Electronic Devices (ربط الأجهزة).
  3. Click Link a New Device (ربط جديد).
  4. In the "Add a Link" window, type a username for the link and choose the income source sequence from the list, then click Add.
  5. The portal user guide says a warning appears at this point: once you link devices, you will not be able to issue invoices on the portal. Read it and continue only if your software will issue all invoices for that activity.
  6. The system generates the user number (Client ID) and the Secret Key and lists them in a table with the income source sequence, the user status and the link's username. Each value has a Copy button.

Copy the values straight into your software's e-invoicing settings. Don't retype them by hand: a single wrong character produces an authentication error that looks the same as a system fault.

Choosing the right income source sequence

The income source sequence identifies the activity the invoices belong to, and it travels inside every invoice your system sends. It is the choice that causes most early problems. Three rules help:

  • One activity, one sequence. If your tax number has more than one income source sequence, generate a separate link for each activity that will send invoices, and make sure each set of invoices goes out under its own sequence.
  • Match the invoice type. An activity registered for general sales tax must send sales tax invoices; one that is not registered sends income invoices without tax lines. ISTD's technical guide lists "This user is not authorized to submit this type of invoice" as the error you get when the two don't match.
  • Separate tax numbers need separate accounts. A branch or company registered under its own tax number logs in with that number and generates its own credentials. Credentials from one tax number cannot send invoices for another.

What your software does with the credentials

ISTD's technical guide says each submission has three components: the Client ID, the Secret Key and the invoice itself as UBL 2.1 XML. The XML is encoded and posted to JoFotara's invoices endpoint, and the two credentials travel in the request header as Client-Id and Secret-Key. You never need to paste them anywhere else. Any vendor asking you to email them a screenshot of the table is asking for more than they need: they only need the values entered once in the settings, ideally by you.

Keeping the credentials safe

ISTD's technical guide is explicit: keeping the Client ID and Secret Key confidential is the taxpayer's responsibility, and the taxpayer bears full responsibility for any unauthorised use. Anyone holding both values can submit invoices under your tax number. In practice:

  • Store them encrypted in your system, never in plain text inside code, spreadsheets or shared drives.
  • Don't send them by email or WhatsApp. If they leak, contact ISTD and replace the link.
  • Limit who can change e-invoicing settings in your software to the owner or an administrator.
  • Keep a record of which link (username) belongs to which system, so you know what to switch off when you replace a POS or accounting program. The link table on the portal shows a status for each one.

Testing the connection and reading the errors

There is no public test environment, so the first test is a real one. Before issuing invoices, run your software's connection test if it has one, then send a first real invoice and check that it appears on the portal and that its QR code scans in the Sanad app. ISTD's technical guide lists the most common HTTP responses, and several point straight at credentials:

ResponseWhat it usually means
403 ForbiddenWrong Client ID or Secret Key
500 Internal Server ErrorUsually a wrong tax number or income source sequence; less often wrong credentials, or a tax rate in the XML that ISTD does not recognise
504 Gateway TimeoutJoFotara could not be reached: your firewall or the national system
400 Bad RequestThe credentials worked but the invoice data is wrong; read the error message in the response

A 200 response is not the end of the check. The guide says to read the invoice status in the response (SUBMITTED, ALREADY_SUBMITTED or NOT_SUBMITTED) and to confirm that a QR code came back. When a request times out, resend the same invoice with the same number and unique identifier rather than generating a new one.

Credentials checklist

  • Active tax number, ISTD e-services account and JoFotara Admin user.
  • One link per activity that sends invoices, on the correct income source sequence.
  • Client ID and Secret Key copied, not typed, into your software.
  • Invoice type (sales tax or income) matching the tax registration of that activity.
  • Separate credentials for any branch with its own tax number.
  • Values stored encrypted, with settings changes limited to administrators.
  • First real invoice accepted, visible on the portal and verified in Sanad.

Once invoices flow, corrections are handled with return invoices, which our guide to credit notes in JoFotara explains.

Where the credentials go in Aspirations

In Aspirations, the Client ID, Secret Key and income source sequence go into the e-invoicing settings, which only the owner or an admin can change. The secret is encrypted and never shown again after saving, and a connection test checks that JoFotara accepts the credentials without creating an invoice. You tick income invoices only if the company is not registered for sales tax, and a branch with its own tax number gets its own credentials. The integration is ready (UBL 2.1) and requires your own JoFotara credentials; during onboarding we review your first real invoices with you in our accounting software.

This guide is general information based on ISTD's published manuals. Screens and procedures can change, so check the current steps with the Income and Sales Tax Department.

Official sources

Frequently asked questions

Where do I find the JoFotara Client ID and Secret Key?

Log in to portal.jofotara.gov.jo with your tax number, username and password, open Linking Electronic Devices, click Link a New Device, enter a username and choose the income source sequence, then click Add. The portal lists the user number (Client ID) and Secret Key with a Copy button for each.

Can a sub-user generate the credentials?

According to the portal user guide, linking devices is done from the main Admin account. Sub-users are created by the Admin to issue invoices on the portal for a particular income source sequence or branch.

Can I still issue invoices on the portal after linking my software?

The portal user guide says a warning appears when you add a link: the taxpayer will not be able to issue invoices on the portal after linking devices. Plan for your software to issue all invoices for that activity, and confirm the current behaviour with ISTD.

Why do I get a 403 error when sending an invoice?

ISTD's technical guide says a 403 Forbidden response points to a wrong Client ID or Secret Key. Copy both values again from the link table on the portal rather than typing them.

Do branches need their own credentials?

A branch registered under its own tax number logs in with that number and generates its own credentials. Within one tax number, generate a link for each income source sequence that will send invoices.