How to authenticate with the REST API

What you can do

Authenticate to the CRIBWISE REST API: create an API key, swap it for a bearer token, and send that token with every call.

You create the key in the Admin Portal. Every ERP REST and BI interface call then needs a token, and tokens expire, so a working integration asks for a new one as it goes.

Important: This article covers the ERP REST interfaces, which run on your own Admin Portal address. The separate paid cloud API on api.cribwise.com is authenticated differently – see Getting started with the CRIBWISE API. If you are not sure which one you are integrating against, check the host name in the URL you were given.

---

Before you start

• You need Admin Portal access with the Manage integrations permission. Without it, Integration does not appear in the Administration menu. See Admin Portal permissions reference.
• You need your base address: the host your Admin Portal runs on, without the portal path. If you open the portal at https://solutionaddress.com/adminportal/yourcompany, the base address is https://solutionaddress.com. This article writes it as [AP_base_uri].
• You need a tool that can send a form-encoded POST request – curl, Postman, or the HTTP client in your integration.

---

Quick start

Experienced users – authenticate in five steps:

1. Open Administration > Integration > API keys in the Admin Portal.
2. Create a key with New key, give it a name, and save it.
3. Copy the Key value that appears on the saved key.
4. POST the key to [AP_base_uri]/adminportalidentity/connect/token with grant_type=client_credentials.
5. Send Authorization: Bearer {access_token} on every API call.

Need more detail? Follow the full steps below.

---

Steps

Step 1 – Open the API keys list

1. In the Admin Portal, open the Administration menu.
2. Select Integration.
3. In the Integration services pane, select API keys.

The API keys list opens. It shows every key on your tenant with its name and expiration date.

API keys sit under Administration > Integration > API keys.

Step 2 – Create a key

1. Select New key.
2. Enter a Name that says which system the key is for, such as ERP integration.
3. If the key should stop working on a set date, select the calendar button next to Expiration date and pick the date.
4. Select Save key.

Field	Required	What to enter
Name	Yes	A label for your own use. It is the only thing that tells two keys apart in the list, so name the system, not the person.
Expiration date	No	The last day the key works. The key stays valid to the end of that day – the list shows the date with the time 23:59. Leave it empty and the key never expires.

A key needs a name. The expiration date is optional and is picked from the calendar.

Step 3 – Copy the key value

The Key field appears only after the key is saved. Its value is your customer short name and a GUID, for example yourcompany_0f14d0ab-9605-4a62-a9e4-5ed26688389b.

1. Select the Copy to clipboard button next to the Key value.
2. Paste the value into your integration’s configuration or secret store.

The Key field only appears once the key is saved. Use the copy button to take the value.

Warning: The key is a password. It grants access to the REST API and the BI interfaces on your tenant, and it stays readable in the Admin Portal for anyone with the Manage integrations permission. Store it the way you store any other secret, and give each integration its own key so you can revoke one without breaking the rest.

Step 4 – Exchange the key for a token

Send the key to the token endpoint. The reply contains the bearer token your calls need.

URL	[AP_base_uri]/adminportalidentity/connect/token
Method	POST
Header	Content-Type: application/x-www-form-urlencoded

Send these body parameters:

Parameter	Value	Notes
client_id	erp_client	Fixed. The same for every tenant.
client_secret	Your API key	The Key value you copied in step 3.
grant_type	client_credentials	Fixed.
scope	erp_api	Fixed.

As a curl command:

curl -X POST "[AP_base_uri]/adminportalidentity/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=erp_client" \
  -d "client_secret={API key}" \
  -d "grant_type=client_credentials" \
  -d "scope=erp_api"

A successful call answers 200 with the token:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "erp_api"
}

Anything else is an error, and the reply names it – see Troubleshooting.

Step 5 – Send the token with every call

Put the access_token in the Authorization header of each API call, after the word Bearer and a space:

Authorization: Bearer {access_token}

For example, calling one of the ERP endpoints listed in CRIBWISE REST API – endpoint overview:

curl "[AP_base_uri]/ERP/PickList/Get" \
  -H "Authorization: Bearer {access_token}"

Success: the endpoint answers 200 with the requested JSON instead of 401. Anything wrong with the header – no token, an expired token, or the token sent without the word Bearer in front of it – answers 401 with the body {"Message":"Authorization has been denied for this request."}.

---

How long a token lasts

The token endpoint returns the lifetime in the expires_in field, in seconds. It is currently 3600 seconds – one hour.

Read expires_in from the reply rather than hard-coding an hour. Then your integration keeps working if the lifetime ever changes.

There is no refresh token. When a token expires, repeat step 4 with the same API key to get a new one. A long-running integration usually keeps one token in memory, reuses it until it is close to expiry, and asks for a replacement then. Asking for a token before every single call also works, but it is wasteful.

---

Manage and revoke keys

You can create as many keys as you need, and every key gives the same level of access. Nothing distinguishes them apart from the name and the expiration date, so use one key per integration.

Change an expiration date

Open the key from the list, select the calendar button, pick a new date, and select Save key. Setting a later date on an expired key makes it work again.

You cannot backdate a key: the Admin Portal rejects a date in the past with Expiration date must be set in the future. To cut off an integration now, delete the key instead.

Delete a key

Select the key in the list, select Delete key, and confirm with Yes. The key leaves the list straight away. Deleting is permanent – a deleted key cannot be restored, and any integration still using it stops working.

Warning: Revoking is not instant. On our test system a deleted key went on issuing new tokens for around two minutes, and a token issued just before the deletion kept working afterwards. If a key has leaked, delete it and treat its access as live until the last token it issued expires.

Note: The delay works in the other direction too. A key you have just created can answer invalid_client for a few minutes – up to four on our test system – before it starts issuing tokens. Wait and retry before assuming you copied it wrong.

---

Authentication with a user name and password (obsolete)

CRIBWISE used to let an integration authenticate as a user with the API users role, by sending grant_type=password with a user name, a password and a customer secret.

That method is obsolete and no longer supported. Move any integration that still sends a user name and password to an API key by following steps 1 to 5 above. The URL, the header and the shape of the response are unchanged – only the body parameters differ, and the integration no longer needs a CRIBWISE user of its own.

The old method also tied API access to a person. An API key does not: it belongs to the tenant, so nobody has to keep a service account’s password alive.

---

Next steps

1. Pick your endpoints – CRIBWISE REST API – endpoint overview lists all of them and explains why a successful response does not always mean the data is in.
2. Read data for reporting – the same key works on the BI interface.
3. Grant the permission – if a colleague cannot see Integration, add Manage integrations to their user group. See How to create and configure a user group.

---

Troubleshooting

Problem	Likely cause	Fix
Integration is missing from the Administration menu	Your user group does not have the Manage integrations permission	Ask an administrator to add the permission to your user group.
The key detail has no Key field	The key has not been saved yet	Select Save key. The value appears afterwards.
400 {"error":"invalid_client"}	The key is wrong, expired or deleted, or client_id is not erp_client	Copy the key again with the copy button. Check the expiration date on the key. If you created the key minutes ago, wait a few more minutes and retry.
400 {"error":"invalid_scope"}	scope is set to something other than erp_api	Send scope=erp_api.
400 {"error":"invalid_grant"}	grant_type is password – the obsolete user authentication	Send grant_type=client_credentials with an API key as client_secret.
401 Authorization has been denied for this request on an API call	The token is missing, expired, or the header does not start with Bearer and a space	Request a fresh token and send it as Authorization: Bearer {access_token}.
404 on an API call, but the token was issued	The base address includes the portal path, or the endpoint path is wrong	Use the host only, with no /adminportal/yourcompany. Check the path against the endpoint overview.

---

Related articles

• CRIBWISE REST API – endpoint overview – every ERP REST endpoint, grouped by resource, and how an asynchronous write behaves.
• Getting started with the CRIBWISE API – the separate paid cloud API on api.cribwise.com, with its own authentication.
• BI interface – the reporting endpoints an API key also opens.
• Admin Portal permissions reference – what Manage integrations and the other permissions allow.
• How to create and configure a user group – where permissions are granted.
• ERP REST Purchase orders – a worked example of a call once you are authenticated.