Skip to main content

DeskOS API: Authentication and Keys

Every section of the DeskOS API (Service Requests, Meeting Rooms, and the sections that follow) is opened with the same kind of key, created in the same place and sent in the same way. This page covers everything that is common: how a human gets a key, what a key can and cannot do, how to send it, what the errors mean, and how an AI agent should behave around it. The per-section pages then cover only their own endpoints.

How it works​

  1. A DeskOS admin opens Developer Settings in the admin console and creates an API key. No DeskOS staff involvement is needed.
  2. While creating it the admin ticks exactly which permissions the key gets, section by section, and optionally restricts it to certain campuses.
  3. Your system sends that key on every request. It can reach only the sections, actions and campuses it was granted, inside the organisation it belongs to.
  4. Every call is written to the access log on the same page, where the admin can see what each key did.

One key can span several sections. A tenant portal that raises tickets and books rooms needs one key with both sets of permissions, not two keys.

Server URL​

All endpoint paths in these guides are relative to your server URL. For most operators this is:

https://oscar.nova.deskos.net

Each section has its own base path under it, for example api/v1/helpdesk/external/ for Service Requests. Developer Settings shows the exact base URL for every section on your workspace. If you run on a dedicated or staging server, use the URL shown there.

Getting an API key​

API keys are self-service. Any admin with the Developer Settings (API Keys) permission can create one.

  1. Sign in to your DeskOS admin console at https://<your-workspace>.deskos.net/admin.
  2. Click your avatar in the top right corner and choose Developer Settings. It is not in the left navigation.
  3. Click Create API key.
  4. Give the key a name that says what will use it, for example n8n facilities automation, Tenant portal or Lobby room display.
  5. Under Permissions, tick what the integration needs. Permissions are grouped by section (Service Requests, Meeting Rooms, ...). Each one names the endpoints it unlocks. Untick anything the integration will not use.
  6. Under Campus access, optionally restrict the key to specific campuses, and pick a default campus so callers do not have to send campus_id on every create.
  7. Set a daily request limit if the default of 1,000 is not right for this integration.
  8. Click Create key. The full key is shown once. Copy it into your integration's secret store straight away.

From the same page you can later edit a key's permissions and campuses, see how many calls it made today and when it was last used, expand its recent calls, revoke it, or reactivate it. The Access log tab shows every call made with any key in your organisation, filterable by key, section, method and outcome.

The key is shown once

DeskOS stores only a hash of the key. If it is lost, revoke it and create a new one. Treat it like a password: never commit it to version control, paste it into a chat, or put it in client-side code.

Who can grant what​

An admin can only put a section on a key if their own role can manage that section. Someone whose role covers Service Requests but not Meeting Rooms can create keys for tickets, and will see the Meeting Rooms permissions greyed out. A key can never do more than the person who created it could do themselves.

A few individual permissions ask for more than their section does, and those are greyed out on their own while the rest of the section stays available. Inspections: meter costs carries money and needs Financials: view as well as Inspections: view. In Visitors, the three that change what happens at the door (invite visitors, cancel and resend invitations, check visitors out) need Visitors: manage rather than Visitors: view, and member check-ins needs Check-ins: view because a member is not a visitor. In every case an admin without the extra permission still grants the rest of the section normally; only those lines stay off.

API key details​

  • Format: dk_live_ followed by 40 hexadecimal characters.
  • Organisation bound: a key belongs to one organisation and can only see that organisation's data. Nothing on the key or in any response reveals other organisations.
  • Permissions (scopes): each key carries a list of scope codes such as helpdesk:requests:create. A call outside its scopes is refused with a 403 that names the missing scope.
  • Campus restriction: optional list of allowed campuses. Without it the key can reach every campus in the organisation.
  • Default campus: optional. Used when a create call does not send campus_id.
  • Daily limit: 1,000 requests per day per key by default, adjustable per key, shared across every section the key can reach. Over the limit the API answers 429 until the next day.
  • Logging: every call is logged against the key (section, method, path, status, IP) and visible in Developer Settings.

Sending the key​

Send the key on every request in one of these three ways.

Authorization: Api-Key dk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

Method 2: X-API-Key header​

X-API-Key: dk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

Method 3: Query parameter​

https://oscar.nova.deskos.net/api/v1/helpdesk/external/teams/?api_key=dk_live_a1b2c3d4...
tip

The query parameter is handy for a quick test in a browser or a no-code tool. Use a header in production so the key does not end up in proxy or browser logs. DeskOS itself never writes the query string into its access log.

A DeskOS user's login session or JWT is not a valid credential for these endpoints, and an API key is not a valid credential for the admin console. The two never cross.

Check a key​

Every section has a GET health/ endpoint that needs no scope. It tells you what the key is and what it can do, which makes it the right first call from any new integration.

curl https://oscar.nova.deskos.net/api/v1/helpdesk/external/health/ \
  -H "Authorization: Api-Key dk_live_..."
{
  "success": true,
  "key_name": "Tenant portal",
  "organization": "Acme Coworking",
  "scopes": ["helpdesk:catalog:read", "helpdesk:requests:create", "meeting_rooms:rooms:read"],
  "default_campus": {"id": 7, "name": "Acme North"},
  "allowed_campuses": [],
  "daily_limit": 1000,
  "requests_today": 12
}

scopes lists every permission on the key across all sections, so one health call is enough to plan the whole integration. An empty allowed_campuses list means the key can reach every campus in the organisation.

Permissions (scopes)​

A scope code is <section>:<resource>:<action>. The per-section pages list their own codes with the endpoints each one unlocks. The sections available today:

SectionScope prefixBase pathGuide
Service Requestshelpdesk:api/v1/helpdesk/external/Service Requests API
Meeting Roomsmeeting_rooms:api/v1/space-management/external/Meeting Room API
Membersmembers:api/v1/accounts/external/Members API
Member Sign-inmember_auth:api/v1/accounts/external/auth/Member Sign-in API
Plans, Passes & Creditsplans:api/v1/plans/external/Plans, Passes & Credits API
Billingbilling:api/v1/orders/external/Billing API
Inspectionsinspect:api/v1/inspect/external/Inspections API
Visitorsvisitors:api/v1/visitor-management/external/Visitors API

More sections will be added here as they open up. A key created today can be edited later to include them.

Campuses​

A DeskOS organisation has one or more campuses (locations). Almost everything belongs to a campus.

  • List endpoints accept ?campus_id= to narrow results. Without it they return everything the key can reach.
  • A campus the key is not allowed to reach is a 404 on list endpoints, the same as a campus that does not exist, so nothing leaks about what is elsewhere. On a create it is a 400 on campus_id.
  • Where a create has to pick a campus (raising a ticket, for example), the order is: campus_id in the body, else the key's default campus, else the organisation's only campus. If none of those applies you get a 400 asking for campus_id.

Ids of things inside a campus (categories, teams, rooms) are per campus. Always fetch them for the campus you are about to act on.

Response shape​

Every response is JSON and carries a boolean success. On failure it also carries errors, keyed by the offending field or by detail.

{"success": true, "count": 3, "teams": [ ... ]}
{"success": false, "errors": {"category_id": "Category not found on this campus."}}

Authentication, permission and rate-limit failures come from the framework layer and carry detail only:

{"detail": "Invalid API key."}

Timestamps are ISO 8601 with a timezone offset, for example 2026-09-12T18:30:00+05:30. Money is a string with two decimals in the currency the response names. Do not assume a symbol.

Errors common to every section​

401: Authentication failed​

{"detail": "Invalid API key."}
{"detail": "API key is deactivated."}

The key is wrong, revoked, or missing. Do not retry with the same key.

403: Missing scope​

{"detail": "This API key does not have the 'helpdesk:requests:close' scope."}

The key exists and works, but was not granted that permission. An admin can add it from Developer Settings without creating a new key.

403: Organisation suspended​

{"detail": "This organisation's DeskOS account is suspended. API access resumes once the account is settled."}

Every key in the organisation is refused until the account is back in good standing. Nothing about the key itself is wrong.

404: Not found​

The record does not exist or is on a campus this key cannot reach. The API does not distinguish the two.

429: Daily limit reached​

{"detail": "Daily rate limit exceeded for this API key."}

Wait for the next day, or ask the admin to raise the key's limit in Developer Settings.

429: Too many invalid keys​

{"detail": "Too many invalid API key attempts. Try again later."}

After 30 requests with an invalid key from one IP address within 15 minutes, that address is locked out for 15 minutes, across every section. A valid key from the same address waits too. A correct call resets the count. If you see this, stop and check the key rather than retrying.

Key hygiene​

  • Rotate by creating a new key with the same permissions, moving the integration to it, then revoking the old one. Revocation is immediate; the next call with a revoked key gets 401.
  • One key per integration. Then revoking one does not break the others, and the access log tells you who did what.
  • Grant the minimum. A room display needs meeting_rooms:rooms:read alone. A ticket-raising webhook needs helpdesk:catalog:read and helpdesk:requests:create. Do not tick everything out of convenience.
  • Restrict campuses when the integration serves one location.
  • Watch the access log. A key calling endpoints it never used before, or from a new IP, is worth a look.

Instructions for AI agents​

This section is written for an AI agent (a coding assistant, an autonomous workflow, or an LLM-powered product) that has been asked to integrate with any part of the DeskOS API. If you are a human reading this, it is also the checklist for what to prepare before you hand the task to an agent. The per-section pages add rules specific to their data.

What you cannot do on your own​

You cannot create, list, edit or revoke API keys through the API. Keys are minted by a human inside the DeskOS admin console. There is no endpoint for it and no way to obtain a key by calling the API without one. Do not try to log in to the admin console, scrape it, or reuse a DeskOS user's session token: those are not valid credentials for this API and the attempt will fail and be logged.

When you need a key, stop and ask the human operator. Ask them for exactly this:

Please create a DeskOS API key and share it with me through a secure channel.

  1. Sign in to your DeskOS admin console, click your avatar in the top right corner and choose Developer Settings.
  2. Click Create API key.
  3. Name it after this integration, for example [integration name].
  4. Under Permissions tick: [list the exact scopes you need, by section].
  5. If you have more than one campus, either restrict the key to the campus this integration serves or set it as the default campus.
  6. Copy the key when it is shown (it appears once) and put it in [the secret store or environment variable you will read, for example DESKOS_API_KEY].

Ask only for the scopes the task needs, and say which section each belongs to. One key can cover several sections, so ask for one key with everything the task needs rather than one key per section.

The human also decides whose account the key is created under. That account is recorded as the actor on anything the key creates or changes.

Handling the key​

  • Read it from an environment variable or secret store. Never hard-code it, never write it into a file that is committed, never echo it into logs, prompts or chat transcripts.
  • If the human pastes the key into a conversation with you, use it and then tell them the key has been exposed in the transcript and suggest they revoke it and create a fresh one once the integration is stored securely.
  • Send it as the Authorization: Api-Key ... header. Avoid the query parameter form in anything durable.
  • If you get 401, the key is wrong or has been revoked. Do not retry. Ask the human for a new one.
  • If you get a 403 naming a missing scope, the key was created without that permission. Do not work around it. Tell the human which scope is missing and ask them to add it to the key in Developer Settings.
  • If you get 429 Too many invalid API key attempts, you have been sending a wrong key. Stop, wait 15 minutes, and check the value with the human before trying again.
  1. Call GET health/ on the section you will use. It confirms the key works and returns scopes, allowed_campuses and default_campus. Check that every operation you plan is in scope before doing anything else.
  2. Read the per-section page for the endpoints, then fetch the reference data (categories, rooms, ...) for the campus you will act on and cache the ids.
  3. Prefer read and preview endpoints (health/, list endpoints, quote/, cancellation preview) to verify connectivity. Do not create real records to test.

Behaviour rules​

  • Respect the daily limit. health/ shows requests_today against daily_limit. Poll at a sensible interval and page lists with page_size up to 100 instead of hammering single reads.
  • Treat 404 as "not visible to this key", not proof that a record never existed. It may be on a campus the key cannot reach.
  • Do not create duplicates. Check existing records before creating on a recurring signal or after a timeout.
  • Do not undo other people's work. Do not close, cancel or change records you did not create unless the human has explicitly asked for that workflow.

Reporting back to the human​

When you finish, tell the human:

  • the key name you used (never the key itself),
  • which scopes it turned out to need,
  • the ids or references of anything you created or changed,
  • any 403 or 429 you hit, so they can adjust the key.

Frequently asked questions​

Can one key be used across several organisations? No. A key belongs to one organisation. Each organisation needs its own key, created by one of its own admins.

Can one key be used across several sections? Yes. Tick permissions from as many sections as the integration needs. The daily limit is shared across them.

Where do I see what a key has been doing? Developer Settings, then the Access log tab. Filter by key, section, method or outcome. Each key card also expands to show its last 50 calls.

How do I rotate a key? Create a new key with the same permissions, move your integration to it, then revoke the old one. Revocation is immediate.

I created a key but a section is greyed out. Your own role cannot manage that section, so you cannot grant it. Ask an admin whose role covers it to create or edit the key.

A section is available but one permission inside it is greyed out. That permission needs more than the section does. Meter costs exposes money, so it needs Financials: view on top of Inspections: view. Inviting a visitor, cancelling an invitation and checking a visitor out need Visitors: manage, and member check-ins needs Check-ins: view. Everything else in the section is yours to grant as normal. See Who can grant what.

Getting help​

Keys, permissions, campus restrictions, limits and revocation are all self-service from Developer Settings. For anything else, reach the DeskOS team through your usual support channel.