Developer docs

1. 1. Verify your company domain.
2. 2. Generate a scoped API key.
3. 3. Send candidate data to the Signal API.
4. 4. Receive structured claims, scores, and a ranking hint.

Candidates do not need a key. They sign in with LinkedIn and approve every claim before anything is shared.

There are two identities. Candidates authenticate with LinkedIn OIDC. The flow starts at /login and returns to /auth/callback, where the backend sets an httpOnly session cookie.

Companies authenticate with scoped API keys. Every request carries a bearer key in the Authorization header. Keys are scoped to the exact operations a team needs.

All endpoints live under the /v1 base path. Companies call them with a scoped API key in the Authorization header. The API origin is set per deployment.

The reference is generated live from the backend. Explore the interactive API reference, or fetch the OpenAPI schema.

curl https://api.xp.cards/v1/cards/{handle}

Nothing personal is public by default. A viewer requests access, and the holder approves, denies, revokes, or expires it. Every grant is scoped and time bound.

Contact fields, documents, and other sensitive data never appear on a public pass. They are released only on the holder's approval.

The public surface is only a QR. It resolves to a request page at /r/{handle}. No personal data is exposed there. The QR confirms that a verified profile exists and lets a viewer ask for access.

Send profile data to the Signal API and receive structured claims, a signal score per claim, risk flags, and a ranking hint. Claims carry a verification level from self claimed up to protocol verified.

XP represents facts as canonical, provenance-ranked attributes. Each fact records where it came from, from self entered to employer or institution attested to document verified, and the highest-trust source wins on conflict.

Verified credentials and professional licenses, skills raised by short assessments, and document-verified identity all feed this model. Sensitive values stay private: contact and documents are released only under an approved grant, and protected data such as date of birth is exposed only as a predicate, never a raw value.

Claims can be confirmed by peers, companies that are domain verified, or institutions. Verification climbs a ladder, from self claimed to institution verified, and shows on the pass and in the signal. Peers cannot confirm their own claims.

Employers search the network by role, location, and signal. Results carry structured, scored, explainable signal and coarse geography. No name and no contact appear until a candidate approves an access request. It is decision support, not an automated decision, and it excludes protected attributes.

Register endpoints with the webhooks:write scope. XP sends signed events for access grants, revocations, and score updates. Verify the signature before trusting a payload.

A candidate issues a Portable Pass over standing that is already public, verification level, publish state, and reputation counts, from GET /v1/candidates/me/portable-pass. The response carries a signed token, shown once. No personal value is included.

A verifier confirms a token at POST /v1/pass/verify with no authentication, since the token itself is the capability, or from the public page at /pass/verify. A valid pass returns the handle, verification state, and reputation counts. An invalid, expired, or revoked token returns valid: false with empty fields.

The pass is signed with an Ed25519 key published as a did:web document at /.well-known/did.json, so a third party verifies it fully offline, with no call back to XP. A candidate may also import an external credential; it lands pending and stays unverified, and it never affects merit or scoring.

Connect an applicant tracking system with the integrations:manage scope. A connection is scoped to your organization from the API key context, never a client header. Connect a provider at POST /v1/integrations/ats/connections; the response carries a per-connection webhook secret, shown once.

Preview the exact minimized payload at POST /v1/integrations/ats/mapping/preview before any push. The payload is pseudonymous by construction: handle, publish and verification booleans, reputation counts, public skill names, and a verify URL. Contact is a boolean only, never a value. Push a candidate at POST /v1/integrations/ats/push and read sync status at GET /v1/integrations/ats/status. In the default build every provider runs inert through the mock.

An ATS notifies XP at POST /v1/integrations/ats/webhook/{provider}. The request names a connection and is authenticated by an HMAC-SHA256 signature over the raw body using that connection's own secret. The tenant is derived server side from the authenticated connection.

A candidate reads a region-aware compliance view at GET /v1/candidates/me/compliance: the resolved jurisdiction, the rights it recognizes, and retention standing. The candidate records consent for a named purpose at POST /v1/candidates/me/consents, lists grants at GET /v1/candidates/me/consents, and withdraws one at POST /v1/candidates/me/consents/{grant_id}/withdraw. purpose and region are coarse codes; no endpoint sends or returns a raw value.

An organization administrator reads the jurisdiction registry at GET /v1/compliance/jurisdictions with the org:admin scope. Each entry lists the framework, the rights it recognizes, the data-subject-request window, and the default retention period. The values are neutral engineering defaults, not legal advice; statutory positions stay a legal decision.

XP records events for the whole access lifecycle, including access requests, approvals, denials, revocations, grants nearing expiry, and verification outcomes. Candidates see every access in their history.

XP is open source and self hostable. Run your own instance and set the web origin with NEXT_PUBLIC_APP_URL and the API origin with NEXT_PUBLIC_API_URL. Configure LinkedIn credentials and webhook secrets on the server only.

The long form guides live in the repository /docs folder and at docs.xp.cards.