Get your credentials

A Partner API credential belongs to one organisation on one PlaySpace host. You apply for it through a public form, PlaySpace reviews the application, and approval provisions the credential automatically. This page is the whole path, in the order you will walk it.

Apply on the host you intend to integrate with, and apply for development first. A credential is bound to the tenant that issued it, so a development credential is refused by production and a production credential is refused by development. There is no configuration in which integration work reaches real clinical data.

---

1. Fill in the application

The form is public and takes no account. It asks for who you are, how to reach you, and how much access the integration needs.

Use a permanent business address. A known disposable or throwaway domain is refused outright, with a message that says so rather than a silent failure. That list is a floor rather than an exhaustive filter, so a temporary address it does not recognise is accepted — which is not a reason to use one. The address you give is where the verification link, the decision and the credential link all arrive, so use one that will still be read in a month.

Pick an access level, or set the permissions yourself. The form offers four named access levels, least to most powerful, each one a bundle of permissions:

• Read-only — read practitioners, clinics, patients, appointments and clinical content, and change nothing. It cannot create clinics or clinicians, so it cannot set an organisation up.
• Scheduling — read-only, plus creating and updating clinics and clinicians, and booking, rescheduling and cancelling appointments. No patient edits, no removals.
• Patient management — Scheduling, plus creating and updating patients. No removals.
• Full administrative access — Patient management, plus removing clinicians, clinics and patients. Every permission on offer.

Your first credential has to be able to create clinics and clinicians. Your organisation arrives empty and this API is the only thing that fills it: a patient needs a clinic and a creating clinician before it can exist, and an appointment needs all three. So Read-only cannot start an integration — it can only read an organisation that somebody has already built. Every level above it can, which is why creating clinics and clinicians sits in all three rather than only in the highest one.

Custom replaces the levels with a checkbox per permission, labelled in plain English. Ask for the narrowest set that does the job — but keep clinics:write and practitioners:write unless you are integrating against an organisation that already exists. You can ask for more later, and widening is an edit PlaySpace makes to your credential rather than a second application.

appointments:delete exists in the vocabulary but no endpoint consumes it, so it is not offered here. Cancelling an appointment is an update, not a delete.

Ask for partner-provided video here if you host your own calls. Ticking "We will supply our own video links" reveals a box for the origins your video links sit on — one per line, each the scheme and host with an optional port and no path, such as https://video.example.com. It is a request rather than a setting: PlaySpace confirms it when your application is approved, and you can still ask for it later through your PlaySpace contact. Leave it unticked to use PlaySpace video, which is what most integrations do. What partner-provided video changes once it is on is on the partner video page.

Submitting answers the same way whether or not you have applied before. That is deliberate: the response says nothing about which organisations already hold a credential. Sending the form many times in quick succession from one network address is refused for a short period, so wait rather than retrying in a loop.

On success the form is replaced by "Thanks — check your email".

---

2. Verify your email

PlaySpace emails you a verification link, with the subject "Verify your PlaySpace partner application". The link opens a page on the same host.

The page does not verify on load. Press "Verify my email". A link scanner or a prefetching mail client would otherwise consume the one-time token before you ever saw the page, so the confirmation is a deliberate press.

The link works once. An unknown link, one that has already been used and one belonging to an application that has moved on all answer the same thing: "This verification link is invalid or has expired." A failure never says which of those it was.

Submitting the form again before you verify replaces the link. A second application for an address that has not verified yet issues a fresh token and retires the previous one, and the new link is emailed to the same address. Open the newest message: the earlier link now fails with the same wording as an unknown one, which is the one case where that message means "you have a better link in your inbox".

Once it succeeds the page reads "Email verified" and your application moves to review.

---

3. While the application is under review

PlaySpace reviews the application and confirms the business agreement that covers it. Approval is where that agreement is recorded, which is why a credential cannot exist before it.

There is no status page, no status endpoint and no progress email. The next thing you receive is the decision:

• Approved — an email carrying a one-time link to your credential. Step 4 below.
• Rejected — an email naming the reason. A rejected application does not block a new one, so you can answer the reason and apply again.

If you send a second application once the first has reached review, it is accepted and nothing further happens. The application already under review is still the one under review. Before that point a second application re-sends the verification link, which is the case step 2 covers.

---

4. Retrieve the credential

The approval email carries a link, never a secret, and its subject begins "Your PlaySpace Partner API application is approved" and ends with your organisation name — so a mail rule that routes it has to match the prefix rather than the whole line. The link opens once and expires 72 hours after approval.

Open it, press Reveal my API credentials, and copy all four values before you close the page:

Put the secret in your secret manager before you navigate away. A second visit to the same link always fails, and the failure is indistinguishable from an expired or unknown one.

If the link expired before you retrieved the credential, reply to the approval email. PlaySpace can reveal the same secret again while the delivery window is still open, and can rotate the credential to a fresh secret after it. Rotation invalidates the previous secret at the authorisation server, so plan a short cutover rather than assuming two secrets can be live at once.

What the page does not hand you. It does not show the token endpoint, and it does not show your partner organisation identifier. Both token endpoints are in step 5. The organisation identifier comes back from the health check in step 6, so one call gets it.

---

5. Exchange the credential for an access token

The credential is an OAuth2 client-credentials pair issued through Auth0. The token endpoint is on the authorisation server, not on the PlaySpace host, and each environment has its own.

The audience, the request body and the token lifetime are identical on both. A credential is bound to the authorisation server that issued it, so posting a production credential to the development endpoint is refused there and never reaches PlaySpace at all — check the host first when an exchange fails.

The exchange below uses the development endpoint.

POST /oauth/token HTTP/1.1
Host: dev-hcp1velit44csg3n.us.auth0.com
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "<client id>",
  "client_secret": "<client secret>",
  "audience": "https://playspace-ehr-api"
}

Do not send a scope field. Your grant is fixed on the credential at approval and travels inside the token. Asking for a permission the credential does not hold fails the exchange with 403 access_denied before PlaySpace is reached at all.

When the exchange fails, read the error field of the body. Two values account for almost every refusal, and they point at different people:

• access_denied — the authorisation server did not recognise this credential, or would not authorise what it asked for. Check the host first, because a credential is bound to the tenant that issued it and a production credential posted to the development endpoint fails exactly here; then check the secret; then check that you sent no scope field.
• invalid_client — the credential authenticated, but PlaySpace has not finished setting it up as a partner organisation. Nothing in your request will clear it. Send us the message and we complete the setup on our side.

Both come from Auth0 directly. The request never reaches PlaySpace, so there is no X-Request-Id on these responses and nothing for us to look up from one — quote the error value and the endpoint host instead.

The response is a standard OAuth2 token response. Take access_token and send it as Authorization: Bearer <token> on every request.

An access token lives 24 hours. Cache it and reuse it until shortly before it expires. Minting one per request is the most common way to hit a rate limit that has nothing to do with your real traffic.

---

6. Check it before you build

GET /v1/partner/health HTTP/1.1
Host: agentic-ps-dev.playspace.health
Authorization: Bearer <access token>

{
  "data": {
    "status": "ok",
    "partner_organization_id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
    "checked_at": "2026-08-24T15:30:00.000Z"
  }
}

This endpoint requires no permissions and answers 200 whenever the token is accepted, so it separates "my credential is wrong" from "my request is wrong" in one call. It also echoes the organisation identifier the token is bound to, which is the only place you will see it.

---

If you already integrate on one host

Apply again, on the other host, through the same form. There is no promotion step and no way to copy a credential across: the two hosts run separate authorisation servers, and a credential is bound to the tenant that issued it.

Everything else about the application is the same, so the second one is usually the fastest thing you do all week.

---

Where to go next

Build the first thing. The quickstart takes this credential to a clinician working inside your product.

Choose how much you build. What you can build sets out the integration levels and what each one costs you.

The credential in detail. Delegated tokens, permissions, refusals and what a browser may hold are on authentication.