Developer docs

One network, two audiences. Companies read the network through a scoped key. Candidates hold their own data and release it by grant.

To start as a company:

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 need no key. They sign in with LinkedIn and approve every claim before anything is shared.

Two identities, two doors. Candidates are people; companies are keys.

Candidates authenticate through Supabase with LinkedIn OIDC. The flow starts at /login, Supabase runs the OAuth exchange, and the browser returns to /auth/confirm, where the session is set as an httpOnly cookie. The backend reads that session at GET /v1/auth/me and ends it at POST /v1/auth/logout.

Companies authenticate with scoped API keys. Every request carries the key as a bearer token in the Authorization header, or as X-API-Key. Keys are prefixed xpk_ and do only what their scopes name.

A company key is assembled from a fixed set: signal:structure, signal:score and signal:rank for the Signal engine; discovery:read to search; vault:request and vault:read for approved contact; credentials:read; verify:write; contribute:write; and webhooks:write.

Every endpoint lives under /v1. Three routes sit at the root: GET /.well-known/did.json, GET /llms.txt, and GET /.

The API origin is configured per deployment through NEXT_PUBLIC_API_URL and defaults to https://api.xp.cards. Versioning is explicit in the path, so an upgrade is a new prefix, never a silent change.

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

curl https://xp-h8fd.onrender.com/v1/cards/{handle}

Privacy is the default state of the network. Nothing personal is public.

A viewer requests access. The holder approves, denies, revokes, or lets it expire. Every grant is scoped and time bound.

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

The public surface is a single QR. It resolves to a request page at /r/{handle}, and the public pass lives at /card/{handle}. Neither exposes personal data.

The gateway confirms that a verified profile exists and lets a viewer ask for access. Identity and contact stay closed until the holder opens them.

The Portable Pass is your verified professional reputation, carried with you anywhere, never trapped in a platform.

It reflects standing that is already public: your verification level and your reputation counts. Every personal identifier is omitted. The pass proves what you are, not who you are: capability and reputation, zero personal data.

A candidate issues the pass from GET /v1/candidates/me/portable-pass. The response carries a signed token, shown once.

Anyone verifies a token at POST /v1/pass/verify with no authentication: the token itself is the capability. A valid pass returns the handle, the verification state, and the reputation counts. The same check runs from the public page at /pass/verify.

The pass is signed with an Ed25519 key, published as a did:web document at /.well-known/did.json. A third party verifies it in seconds, fully offline, with no call back to XP.

The same pass serves a person and an AI agent equally.

Send profile data to the Signal API. Receive structured claims, a signal score per claim, risk flags, and a ranking hint.

Every claim carries a verification level, from self claimed up to protocol verified. The score reflects evidence, not adjectives.

XP stores facts as canonical, provenance-ranked attributes. Each fact records its source, from self entered to employer or institution attested to document verified. On conflict, the highest-trust source wins.

Verified credentials and licenses, skills raised by short assessments, and document-verified identity all feed the 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 as a predicate, never a raw value.

Trust climbs a ladder: self claimed, evidence attached, peer verified, company verified, institution verified, protocol verified. Each rung is earned, and the level shows on the pass and in the signal.

Peer verification requires external validation, a peer cannot confirm their own claim. The higher rungs come from domain-verified companies and from institutions.

Employers search the network by role, location, and signal. Results are pseudonymous: structured, scored, explainable signal and coarse geography. No name and no contact appear until the candidate approves a request.

A company's own contact lists are never matched against XP's candidate base. Discovery reads only what a company itself attaches; upload is not lookup. Silence is indistinguishable from non-existence.

It is decision support, not an automated decision, and it excludes protected attributes.

XP for Business is built for a reader that is mostly not human. The console is an agent surface first. People enter at the two points that matter: they set the objective, and they sign what leaves the organization.

The candidate side is the mirror image. A candidate is a person, their pass is an empty envelope, and nothing about them moves without their grant.

One line divides every capability. Reading is free: discover, rank, list openings, read requests. An agent never asks permission to look. Anything that leaves the organization needs a signature: requesting a vault, issuing or revoking a credential, publishing a public page, inviting a member. The agent proposes; a human accepts.

An irreversible act never executes inline. It becomes a proposal in a queue, and no agent tier is trusted enough to skip it.

An agent is a first-class object owned by an organization: a name, a scope set, a rate ceiling, an audit trail, and a revoke button , never a bare key. Its scopes are a subset of the member who created it, so an agent can never exceed its creator. Agents authenticate with xpa_ tokens at POST /v1/mcp/employer; the token is shown once and revocation is immediate.

Agents can discover this surface without a human. GET /llms.txt states the line, both MCP doors, the token families, and the approval endpoints.

One rule is permanent: Core Sync reads only what a company itself attached, and never joins against XP's candidate base. Matching a contact list against XP profiles would turn the network into an enumeration oracle, upload ten thousand addresses, learn which have a profile. That is the precise opposite of what XP is.

Connect any LLM to XP through the Model Context Protocol. A candidate or company turns on XP Pilot and, in one tap, authorizes an assistant to act on their behalf. XP's native pilot runs by default, so no external account is required.

Authorization mints a scoped, revocable, delegated token that is never shown to the user. Candidate pilots authenticate with xppa_ tokens at POST /v1/mcp; organization agents use xpa_ tokens at POST /v1/mcp/employer. Contact and sensitive data are never released without an explicit clearance the holder approves.

Every action is audit logged. Tokens expire and can be revoked in one tap. One MCP server serves every assistant: Claude natively, with others as they adopt the protocol.

Register endpoints with the webhooks:write scope. XP delivers signed events across the access lifecycle, such as signal.scored, vault.access_granted, vault.access_revoked, and credential.revoked.

Every delivery carries an HMAC-SHA256 signature over the raw body, a timestamp, and an event id. Verify the signature with your shared secret before you trust a payload.

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. It is pseudonymous by construction: handle, publish and verification booleans, reputation counts, public skill names, and a verify URL. Contact is a boolean, never a value.

Push a candidate at POST /v1/integrations/ats/push and read sync status at GET /v1/integrations/ats/status.

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.

Consent is recorded for a named purpose at POST /v1/candidates/me/consents, listed at GET /v1/candidates/me/consents, and withdrawn at POST /v1/candidates/me/consents/{grant_id}/withdraw. Purpose and region are coarse codes; no endpoint 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 data-subject-request window, and the default retention period. These are engineering defaults, not legal advice.

XP records the full access lifecycle: requests, approvals, denials, revocations, grants nearing expiry, and verification outcomes.

Candidates see every access in their history.

XP is open source and self-hostable. Set the web origin with NEXT_PUBLIC_APP_URL (defaults to https://xp.cards) and the API origin with NEXT_PUBLIC_API_URL (defaults to https://api.xp.cards). LinkedIn credentials and webhook secrets stay on the server, never in the client.

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