Skip to main content

Your first call

You have received your OAuth credentials and obtained an access token (Authentication). This page walks you through your first successful authenticated request and gives you your workspace_id, the workspace identifier required for subsequent calls. There is no sandbox: you call production with your production account. Both endpoints on this page are reads: they create nothing, send nothing to a third party, and change nothing in the workspace - that is exactly why they make the first call.

Step 1: check that the API responds​

GET /api/v1/health confirms that the API is reachable, without authentication.

curl https://app.scribee.tech/api/v1/health
{
  "status": "ok"
}

This endpoint responds status: "ok" as soon as it is reachable; it does not publish availability metrics. It accepts 60 requests per minute per IP address.

Step 2: list your workspaces​

GET /api/v1/workspaces returns the workspaces your OAuth client has access to; the read scope is sufficient.

curl https://app.scribee.tech/api/v1/workspaces \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response abridged to the fields useful here (each workspace also carries created_at and updated_at):

{
  "data": [
    {
      "id": 42,
      "name": "ACME Workspace"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total_pages": 1,
    "total_count": 1
  }
}

The list is paginated (page, per_page - 20 by default, 100 maximum) and sortable (sort_by: name, created_at, or updated_at; sort_order: asc or desc; default sort: name ascending). The data + meta envelope and pagination are the rule on list endpoints, but not a universal guarantee: a few naturally bounded lists - an invoice's payments, for one - return data alone, with no meta and no pagination. The exceptions are catalogued in API conventions; do not hard-code the presence of meta.

An empty data array is not an error: either no workspace has been attached to your OAuth client yet (ask your Scribee contact for the attachment), or the IPv4 allowlist of the workspaces concerned excludes your IP address (see below).

Step 3: build your next calls​

The id field of each workspace is the workspace_id. Endpoints that list or create resources are nested under /api/v1/workspaces/{workspace_id}/: for example, the invoices of workspace 42 are listed at /api/v1/workspaces/42/invoices. Endpoints that operate on an already-identified resource most often reference that resource directly by its id, without workspace_id in the path. Note this identifier once; it is stable over time.

What happens next​

  • Nothing. These two calls have no side effects: no resource created, no transmission to the PPF (Portail Public de Facturation), the Peppol network, or a recipient. You can replay them as many times as necessary.
  • IP filtering already applies to the list itself: a workspace whose IPv4 allowlist rejects your address is removed from the response of GET /api/v1/workspaces, without error. A list shorter than expected can therefore signal an IP address issue, not an access removal.
  • Attaching a workspace to your OAuth client is done by a Scribee administrator. A new workspace appears in the list as soon as this attachment is made, with no action needed on your side.

Errors and edge cases​

401 Unauthorized​

Missing, expired, revoked, or invalid token. The response body is empty; the WWW-Authenticate header specifies the cause. Request a new token at /oauth/token (Authentication) - tokens expire, your integration must know how to request a new one.

403 Forbidden: workspace access​

On an endpoint prefixed with {workspace_id}, if your OAuth client is not attached to that workspace:

{
  "error": "forbidden",
  "message": "L'application n'a pas accès à cet espace de travail"
}

Check the workspace_id against the list from step 2. If it is correct, ask your Scribee contact for the attachment.

403 Forbidden: IP address denied​

If the workspace's IPv4 allowlist is configured and rejects the request's source address:

{
  "error": "forbidden",
  "message": "Cette adresse IP n'est pas autorisée pour cet espace de travail"
}

Ask your Scribee contact to add your servers' outbound IPv4 address to the workspace's allowlist. An empty allowlist allows every address.

The allowlist only knows IPv4: as soon as it holds at least one entry, a request arriving from an IPv6 address is denied and no entry can ever authorize it. If your servers egress dual-stack, force IPv4 towards app.scribee.tech before asking for an allowlist.

400 Bad Request: page beyond the last​

On GET /api/v1/workspaces, requesting a page beyond the last page of a non-empty collection returns:

{
  "error": "bad_request",
  "message": "Le numéro de page dépasse le nombre de pages disponibles"
}

Start again from page=1 or bound your requests with meta.total_pages. This message only covers a page that is too large. An invalid page value - page=0, a negative, empty, or non-numeric value, or one sent in array form (page[]=1) - returns the same 400 status and the same error key, with a distinct message: "Le numéro de page doit être un entier supérieur ou égal à 1". Always send an integer page greater than or equal to 1.

429 Too Many Requests: health check limit​

Beyond 60 requests per minute per IP address on /api/v1/health, the response is a 429 status with a Retry-After header. Space out your calls; the limit resets the following minute.