# InternRelay authentication

InternRelay supports anonymous public internship discovery, browser sessions, account API tokens, and OAuth 2.0 authorization-code access for approved agent clients. Private application data and side-effecting application actions require a verified InternRelay principal and the matching scope.

## Discover

Read [protected-resource metadata](https://www.internrelay.com/.well-known/oauth-protected-resource), [authorization-server metadata](https://www.internrelay.com/.well-known/oauth-authorization-server), and [the developer guide](https://www.internrelay.com/developers.md) to identify the resource host, issuer, endpoints, and supported scopes. The resource identifier is https://www.internrelay.com.

## Pick a method

For public discovery, no credential is needed. For an external agent, use OAuth 2.0 Authorization Code with S256 PKCE. For a user-managed integration, a signed-in InternRelay user can create a scoped account token at `/dashboard/tokens`. A browser session remains the human path for account and application actions.

## Register

Register a public OAuth client with [POST /api/oauth/register](https://www.internrelay.com/api/oauth/register). Send JSON containing `client_name`, `redirect_uris`, and a supported `token_endpoint_auth_method`. Redirect URIs must use HTTPS or a loopback HTTP address. Create a human account through [the sign-up page](https://www.internrelay.com/auth/sign-up) when needed.

## Claim

Start authorization with [GET /api/oauth/authorize](https://www.internrelay.com/api/oauth/authorize), including the registered client ID, exact redirect URI, `response_type=code`, state, requested scopes, and an S256 PKCE challenge. The signed-in user reviews the requested permissions on the consent page reached through the authorization redirect. InternRelay does not advertise a WorkOS `identity_assertion` or ID-JAG claim endpoint; a User-Agent, prompt email, or unverified header is not an identity claim.

## Exchange

Exchange the one-time authorization code at [POST /api/oauth/token](https://www.internrelay.com/api/oauth/token) using `grant_type=authorization_code`, the same redirect URI and client ID, and the PKCE verifier. Refresh with `grant_type=refresh_token`; the server rotates refresh tokens.

## Use the access_token

Send the opaque access token as `Authorization: Bearer <access_token>` to protected API, MCP, or agent operations. Request only the scopes needed: `internships:read` reads public listings, `applications:read` reads the signed-in candidate's 100 newest applications, and `applications:write` submits as that candidate. The application action requires clear user confirmation before the call.

## Errors

A protected resource returns HTTP 401 with `WWW-Authenticate: Bearer` and a `resource_metadata` URL when credentials are missing or invalid. A valid token without the required scope returns HTTP 403. API errors use JSON with a code, message, resolution hint, and request ID. Treat HTML sign-in pages as human-facing responses and do not parse them as API JSON.

## Revocation

Revoke an OAuth access or refresh token with [POST /api/oauth/revoke](https://www.internrelay.com/api/oauth/revoke). A user-managed account token can be revoked from [Agent access tokens](https://www.internrelay.com/dashboard/tokens). Sign out from the browser to end the current session.

## agent_auth

The WorkOS `agent_auth` extension is not used for this OAuth profile. `identity_endpoint`, `claim_endpoint`, `events_endpoint`, and `identity_assertion` are therefore absent from the authorization-server metadata. `service_auth` and `id-jag` are not accepted credential types. The supported credential is an OAuth bearer access token, and protected resources expose the `WWW-Authenticate` metadata hint described above.

For help, email support@internrelay.com.