Creating users through the API

How users (identities) come into being in the Coassemble API, why there's no create-user endpoint, and what to send so the first call succeeds.

You don't create a user with a separate call. A user, the identity behind an identifier, is created automatically the first time a request succeeds with that identifier: for example, issuing an embed with POST /v1/headless/embed/course or POST /v1/headless/embed/agent, or minting an Embed agent token with POST /api/v1/agent/auth. Once it exists, you can read it with GET /v1/headless/user/{identifier} and update it with PUT /v1/headless/user/{identifier}.

What creates a user?

Any of these, the first time it succeeds for a new identifier:

• Issuing an embed: a course (view or edit), collection, screen, agent or analytics embed, through the /v1/headless/embed/... endpoints.
• Minting an Embed agent token with POST /api/v1/agent/auth.
• Duplicating a course with an identifier in the request body.

Later calls with the same identifier reuse the same user, so progress and courses stay with them. Always send the same stable identifier for a person, such as your own user ID. A new or changed identifier is treated as a new user.

If you pass a clientIdentifier, the user is created under that client, and the client is created too if it doesn't exist yet. Don't use personal data such as names or email addresses as a clientIdentifier, because the identifier is kept after deletion.

Why does PUT /user/{identifier} return "User not found"?

PUT /v1/headless/user/{identifier} only updates a user that already exists. It never creates one, so for a new identifier it returns 404 User not found. If you send a clientIdentifier that doesn't exist, it returns 404 Client not found. Make one of the calls above first, then update the user.

What do I need to send to the agent embed?

POST /v1/headless/embed/agent needs:

• mode: create (a new course from the intake) or coach (chat editing an existing course). Any other value returns 400 mode must be create or coach.
• identifier: your stable identifier for the person.
• courseId: required when mode is coach. Without it you get 400 courseId is required for coach mode.

clientIdentifier is optional, along with name and avatar for how the person appears.

Frequently asked questions

Is there a POST endpoint to create a user?

No. Users are created by the calls above. Use GET /v1/headless/users to list the users you have, optionally filtered by clientIdentifier.

Are users created with a Test API key kept separate?

Yes. A Test key creates and sees its own test users, separate from the users your Production keys create.

Can I send a blank identifier?

No. A blank identifier is refused with a 400 error.

How do I delete a user?

Use DELETE /v1/headless/user/{identifier}. You can choose what happens to the courses associated with that identifier.