Access

The token belongs to your organization, not to a person. A token, sometimes also called a key, is a long string of characters that works like a password for programs. Your system uses it to authenticate with the API. With the token, your system reads the tenders that procuris knows. Which part of them it fetches, it controls itself through filters.

Making a request

The token goes in the Authorization header. It is preceded by the word Bearer and a space. The request goes over HTTPS to https://api.procuris.eu. Paths start with the version /v1:

GET /v1/tenders/e9da30eb-50e6-47f1-887f-434016267b2f HTTP/1.1
Host: api.procuris.eu
Authorization: Bearer <your token>
Accept: application/json

The API responds with JSON in UTF-8. It rejects requests over unencrypted HTTP. The rejection only comes, however, after the token has already crossed the network in plain text. If your system has ever sent a token over HTTP, treat it as exposed, see Token lost or exposed.

Read, not write

The API only reads. It knows two requests, both with GET:

Your system cannot change anything in procuris through the API. Saved searches, the board and workbooks stay untouched.

Creating a token

Only the role Owner creates tokens. This happens in the API access section under Settings › Organization. The section appears only once access has been set up after the contract is signed, and even then only the role Owner sees it. Until then, the API access row in the On request section of the same page only requests a quote. Your IT builds the request. It gets the token from the owner.

1. The owner chooses Create token and gives the token a name, for example "CRM sync".
2. procuris shows the token once. After that it cannot be read again, not even by procuris.
3. The owner passes the token to your IT through a password manager instead of email or chat, because messages stay behind in mailboxes and histories.
4. Your IT stores it in the secret store of the fetching system, not in the source code, because source code gets copied and shared. A secret store is a protected place for credentials that only the fetching program and a few people may read.

Tokens do not expire on their own. Rotate them regularly anyway, for example once a year. A token that was copied without anyone noticing is then worthless after that year at the latest. If someone with access to the token leaves the company, rotate it as well, because that person could otherwise keep using it.

Rotating a token without downtime

Two tokens valid at the same time allow rotation without downtime. An organization can have up to two tokens, and both share the request limit. If two tokens already exist, the owner first revokes the one that no system uses anymore. Only then is there room for a new one.

1. The owner creates a second token under API access.
2. Your IT enters the new token in your system and tests a request.
3. The owner removes the old token under API access with Revoke.

If two systems use one token each, for example CRM and ERP, rotate one token after the other. A third token is not possible. So the system whose token is being rotated borrows the other system's token for the duration of the rotation:

1. Your IT temporarily enters the ERP's token in the CRM and tests a request.
2. The owner revokes the old CRM token and creates a new one.
3. Your IT enters the new token in the CRM. The ERP keeps running with its own token the whole time.
4. For the ERP, you repeat steps 1 to 3 with the roles swapped. The ERP then borrows the new CRM token.

Both systems keep fetching without a pause during the rotation. The request limit does not change, because it applies to both tokens together anyway.

Token lost or exposed

The owner revokes and replaces tokens themselves under API access. A revocation takes effect from the next request.

• Exposed: If the token appears, for example, in a code repository or an email, the owner revokes it right away and then creates a new one. The sync pauses until your IT has entered the new token. This pause weighs less than a token that strangers know.
• Lost: If the token can no longer be found but is not public, the owner creates a new one and then revokes the old one. If two tokens already exist, the owner revokes the lost one first.
• Emergency: If nobody with the role Owner can be reached, write to support@procuris.eu. We revoke the token after checking back with your organization. The owner then creates a new token.

A revoked token leads to the response 401.

Errors

Errors come as an HTTP status with a description in JSON. The description is in the response body (the part of the response after the headers). Its format is application/problem+json according to RFC 9457, the internet standard for error messages from interfaces:

{
  "type": "https://docs.procuris.eu/docs/api/zugang#fehler",
  "title": "Invalid token",
  "status": 401,
  "detail": "The token is unknown or revoked.",
  "instance": "/v1/tenders"
}

Limits

Unless your quote says otherwise, 60 requests per minute apply. The limit applies per organization, across both tokens together. Your quote can include higher limits.

Three headers show how many requests are still free. They are in every response to a request with a valid token. For a 401 response, procuris recognizes no organization, so the headers are missing there.

Above the limit, the API responds with 429. The Retry-After header gives the wait time in seconds.

An hourly sync stays far below the limit: 1,000 changed records at 100 per page need 10 requests, while the limit allows 60 per minute.

Related pages

• API: first request
• Data model
• Filters and timing