Get access¶
This is step zero. To call the Cognassist API you need one thing: a client id and client secret issued to your organisation. This page tells you what to send, where to send it, and what you get back, so your first action is unambiguous.
You ask Cognassist for credentials, we confirm the request and issue your clientId and clientSecret, and you exchange those for a token on every run. There is nothing to install and no sandbox to spin up first.
The one route¶
Requests go through a single front door: the Get support link, the same destination in the top navigation of this site. Open it and say you need API credentials for an integration.
If you are already working with a Cognassist account manager or onboarding contact, they can raise or fast-track the request for you. There is no self-service credentials form. Either path lands in the same place, so you do not need to choose the "right" one.
What to send¶
Include these four things so we can issue the right credentials without a round trip:
| Send this | Why we need it |
|---|---|
| Organisation name | The credentials are scoped to one organisation. |
| UKPRN | Confirms which registered provider the data belongs to. |
| Intended use | A one-line summary, for example "sync assessment results into our ILP". |
| Systems you are connecting | For example your MIS or e-portfolio, and any assistive tooling such as Power Automate. Tells us what you are integrating with. |
You do not send any secret, key, or certificate to get started. Credentials are issued to you, not supplied by you.
What you get back¶
We issue your clientId and clientSecret. That pair is all you need to authenticate.
You never send them on ordinary API calls. You exchange them once for a short-lived bearer token, then send that token as Authorization: Bearer <token> on every other request. POST /v1/auth is the only endpoint that does not itself require a bearer token. The full token flow, including lifetime and caching, lives on Getting started, which also covers handling the client secret safely. For the exact request and response schema, see the API reference.
Treat the client secret like a password: store it in a secret manager or environment variable, never in source control or client-side code. If it is ever exposed, contact support to have it rotated.
What credentials cover¶
Your credentials are scoped to a single organisation: every endpoint only ever returns that organisation's learners. The full access model, including the 403 Forbidden you get for another organisation's resources, is documented once in Core concepts.
Your organisation is a single client: request one clientId and clientSecret for the whole organisation, rather than one credential set per site. One more thing about that scope is worth knowing before you request credentials.
Tutors are provisioned separately, in the app¶
API credentials authenticate a system, not a person, and there is no endpoint to create or list tutors. Tutors are set up inside the Cognassist app. This matters because creating a learner requires a primaryTutorEmail, and that tutor must already exist in Cognassist before your first create call succeeds. Provision the tutors you need first. See Troubleshooting if a primaryTutorEmail is rejected.
Before you write code¶
You now have the one thing that unblocks everything else. A sensible order from here:
- Test safely. How to try the API without touching live learner data. Confirm your testing approach with your Cognassist contact first.
- Getting started. Exchange your credentials for a token and make your first calls, from create through to a result.
- Planning your integration. The three phases and the decisions that shape the build.
Newer to Cognassist? Before you start sets the context before this step.