# Studid

> Studid is an academic verification API. It confirms a user's institutional affiliation through their university's existing SAML 2.0 single sign-on. Two REST endpoints; the integrator needs no SAML knowledge.

Use Studid to verify students, researchers, faculty and alumni without collecting documents or passwords.

## API

Base URL: https://api.studid.io

- `POST /v2/auth/verification` — create a verification session.
  Body: `{ "secretToken": string, "redirectUrl": string, "serviceName": string, "mode"?: "live" | "test" }`
  Returns `{ "id": string, "link": string }`. Redirect the user to `link`.
- `GET /v2/auth/verification/{id}?id={id}&secretToken={secretToken}` — check status.
  Returns `{ "id": string, "created": string, "session": object | null }`. Poll every 2–5 seconds; `session` is `null` until the user completes login.
- `GET /v2/entities/{id}` — institution info (display names, country, logos).
- `GET /openapi.json` — OpenAPI 3.0 spec.

## Session fields

```
session: {
  authIdentifier: string | null   // use for user accounts
  authIdentifierType: "pairwise-id" | "persistent-nameid" | null
  entityId: string                // institution, always present
  affiliations: string[]          // role values, often empty
  test: boolean                   // true for test-mode logins
}
```

- `authIdentifier` is `null` when the institution issues no usable stable ID (a transient or `emailAddress` NameID). The verification is still valid: `entityId` always identifies the institution, so use it for eligibility decisions plus per-session tracking.
- `affiliations` is often empty because Studid is not a REFEDS R&S entity. This is expected; do not treat it as a failed login.
- `entityId` is always present and identifies the institution.
- Reject `test === true` sessions in production.

## Integration notes

- Two calls, no SDK: create a verification, redirect the user, then poll the result.
- No account, API key or credit card is required.
- Rate limits: 100 requests / 60s per IP globally; 20 requests / 60s on `/v2/auth/*`.
- Verifications expire after 60 minutes; the SAML link is valid for 30 minutes.
- Test mode: pass `"mode": "test"` to restrict login to the DFN test IdP and tag sessions with `test: true`.

## Docs

- Integration guide: https://studid.io/guide
- Interactive API reference: https://studid.io/docs
- OpenAPI spec: https://api.studid.io/openapi.json
- Open-source better-auth plugin: https://github.com/andrwagn/stud

## Coverage

Institutions whose identity providers are members of an eduGAIN-participating national federation (70+ federations, thousands of universities and research organizations worldwide).