People API Integration Guide

1. What this is
2. Getting a key
3. Adding a person
4. The fields
5. Responses
6. Code examples
7. What a key cannot do
8. Security checklist
9. What is not in this version

What this is

One HTTPS request that creates a person in your organisation, exactly as an administrator would in the console. TatvaOS gives them an address on your verified domain, applies your plan's limits, and sends them an invitation to set their own password.

It is deliberately small: one endpoint, one authentication method, and a handful of fields.

At a glance

1. Getting a key

An organisation administrator creates keys in the TatvaOS admin: Organisation → API keys → People API. They name the key for the program that will use it ("Student information system"), tick what it may do, and hand it to you. It looks like this:

tvk_m4Kp9vRt2xQn7bLw3sHy6dFz8cJaG5eU

It is shown once. TatvaOS stores only a hash with a short visible prefix, so a list can tell two keys apart. Nobody can read the key back, including us. If it is lost, the administrator revokes it and creates another.

It does only what was ticked. Today there is one thing to tick — adding people — and a key with nothing ticked can do nothing at all. An unticked permission is refused by the server, not merely hidden in the console.

2. Adding a person

One POST, JSON body, key in the Authorization header.

POST /api/v1/org/people HTTP/1.1
Host: core.tatvaos.com
Authorization: Bearer tvk_m4Kp9vRt2xQn7bLw3sHy6dFz8cJaG5eU
Content-Type: application/json

{
  "localPart":     "asha.rao",
  "displayName":   "Asha Rao",
  "recoveryEmail": "asha.rao@example.com"
}

That creates asha.rao@your-verified-domain and sends Asha an invitation at her personal address. She follows the link and chooses her own password. Nobody — not you, not your software, not the administrator — ever sets it or sees it.

Which domain

If your organisation has one verified domain, leave domainId out and TatvaOS uses it. If you have more than one, the request is refused with a message listing them and their ids, because guessing which domain a person belongs on is not a guess worth making.

3. The fields

4. Responses

Every response is JSON. Read the status code first, then the body.

Retries

Retry a 429 after a pause, and a network failure at once. Do not retry a 409 — the person is already there. Do not retry a 400, 401 or 403 unchanged; the same request gets the same answer.

5. Code examples

Each adds the same person. Replace the key and the addresses.

curl

curl -X POST https://core.tatvaos.com/api/v1/org/people \
  -H "Authorization: Bearer $TATVAOS_PEOPLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"localPart":"asha.rao","displayName":"Asha Rao","recoveryEmail":"asha.rao@example.com"}'

Node.js (18+, built-in fetch)

const res = await fetch("https://core.tatvaos.com/api/v1/org/people", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.TATVAOS_PEOPLE_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    localPart: "asha.rao",
    displayName: "Asha Rao",
    recoveryEmail: "asha.rao@example.com",
  }),
});
const body = await res.json();
if (res.status === 409) return;                       // already there, nothing to do
if (!res.ok) throw new Error(`${res.status}: ${body.error}`);

Python (requests)

import os, requests

r = requests.post(
    "https://core.tatvaos.com/api/v1/org/people",
    headers={"Authorization": f"Bearer {os.environ['TATVAOS_PEOPLE_KEY']}"},
    json={
        "localPart": "asha.rao",
        "displayName": "Asha Rao",
        "recoveryEmail": "asha.rao@example.com",
    },
    timeout=30,
)
if r.status_code == 409:
    pass                                              # already there
elif not r.ok:
    raise RuntimeError(f"{r.status_code}: {r.json().get('error')}")

A joiners feed, end to end

The pattern most integrations follow. Your system holds the list of people who have joined. Nightly, or on each new record, it sends one request per person. Treat 409 as success — it means that person is already in TatvaOS, which is what you wanted — and you can re-send the whole list safely without creating duplicates.

Keep your own record of who you have sent, so a failure part-way through a batch can be resumed rather than restarted.

6. What a key cannot do

Stated plainly, because these are the questions a careful administrator asks before handing a credential to a program.

• It cannot make anyone an administrator. Only employee is accepted. Asking for an admin or owner role is refused, and so is inheriting one through a department whose default role is privileged. A key cannot escalate by any route.
• It cannot set anyone's password. There is no password field. People set their own from the invitation.
• It cannot read your people. There is no list or lookup call yet. The key adds and nothing else.
• It cannot remove, suspend or edit anyone. Those stay in the console, where a person decides them.
• It cannot reach another organisation. The key names yours, and every read and write is confined to it by the database, not only by the code.
• It cannot send mail. That is the separate Mail API key.

7. Security checklist

8. What is not in this version

Stated so you can plan around it rather than discover it.

Each of those is a decision about what a stolen key could do, which is why none of them has been added quietly.