Skip to main content
Sign in with HUD lets the users of your product connect their HUD account over OAuth. Your product then calls the REST API on each user’s behalf with their own access token, so you never handle their API keys and each user’s access can be revoked on its own. Every user acts as a member of your team. Their work belongs to your team, and its billing, spend limits, roles, and admin controls apply exactly as they do for API keys.
Sign in with HUD is available on the Enterprise plan. HUD registers your application; to set one up, contact HUD.

​
Set up your application

Tell HUD which team the application belongs to, its name, and its redirect URIs. HUD registers it and sends you its client ID and client secret. Keep the secret on your server. Each application belongs to exactly one team; a team can have several. Your users see the application’s name on HUD’s consent screen and choose whether to allow it.

​
Scopes

Request the scopes your product needs. The user sees them on the consent screen.

​
Sign a user in

HUD uses the OAuth 2.0 authorization code flow with PKCE (S256) at https://clerk.hud.ai.
1

Send the user to HUD

Redirect the user to the authorization endpoint. They sign in to HUD and approve the scopes.
HUD redirects back to your redirect_uri with code and your state.
2

Exchange the code for tokens

From your server, exchange the code for an access token (it starts with oat_) and, with offline_access, a refresh token.
3

Add the user to your team

A user who is not yet a member of your team must join it once. Joining is idempotent, so you can call it after every sign-in.
The response is the user’s membership: membership_id, team_id, and role. New users join with the External role; current members keep their role.
4

Call the API

Send the access token as the bearer token, exactly like an API key.
To identify the user in your product, call the userinfo endpoint with the access token. sub is the user’s stable HUD ID; link accounts on it rather than on email. name and email need the profile and email scopes.

​
Keep and end access

Access tokens expire after the expires_in seconds in the token response. Refresh them from your server. Each refresh returns a new access token and a new refresh token, and the previous access token stops working, so store both.
To sign a user out, revoke their token. HUD stops accepting a revoked token within a minute.

​
What users can do

A token acts as the user’s membership in your team. It has that member’s access, no more, and shares the rate limit of their API keys. With hud:api, tokens reach environments, tasksets and tasks, imports, data files, jobs, rollouts, traces and trace storage, models, builds, checks, QA agents and QA checks, limits, usage, and the team member list. Secrets, provider keys, completions, and instances refuse OAuth tokens, as does everything outside the public API. The REST API reference lists the endpoints by group. New users join as External members, who see only their own work and what is shared with them. To give a user access to the team’s shared environments, tasksets, and jobs, a team admin changes their role to Member in Settings → Members, or through the REST API with a hud:team token.

​
Manage users

Users who joined through your application are listed in Settings → Members with everyone else, and admins manage them the same way. Removing a user ends their access: their tokens are refused with membership_unavailable, and they can’t rejoin through your application until an admin invites them again. Unregistering the application stops all of its tokens within a minute. Its users stay members of the team.

​
Errors