> ## Documentation Index
> Fetch the complete documentation index at: https://trygradient.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How people sign in to Gradient, how they join your organization, and how candidate links work

# Authentication

Everyone on your hiring team signs in at
[app.trygradient.ai/login](https://app.trygradient.ai/login). Candidates do not sign in at all.
This page covers both, and the three ways a person becomes a member of your organization.

## How your team signs in

Gradient supports four sign-in methods. Which ones you see depends on how your organization is
set up.

<CardGroup cols={2}>
  <Card title="Email magic link" icon="envelope">
    Enter your work email. Gradient sends a link that signs you in. No password to store.
  </Card>

  <Card title="Password" icon="key">
    Set a password and sign in with it. Use **Forgot password** on the sign-in page to reset it.
  </Card>

  <Card title="Google" icon="google">
    Sign in with your Google work account.
  </Card>

  <Card title="Single sign-on" icon="building-lock">
    Sign in through your company identity provider with SAML or OIDC. Available on enterprise
    plans. See [Single sign-on](/docs/guides/sso).
  </Card>
</CardGroup>

<Note>
  If your organization enforces single sign-on, the other three methods are turned off and the
  sign-in page shows only the SSO button. That is the policy working correctly.
</Note>

### Sessions

A session lasts **seven days**. After that you sign in again. **Sign out** ends the session
immediately on the server, not only in your browser, so a signed-out session cannot be reused.

Signing out on one device does not sign you out on the others.

## How a person joins your organization

<Steps>
  <Step title="By invitation">
    An owner or an admin adds the person at **Settings, Team** and picks their role. Most people
    should get **member**, which can run a hiring process but cannot change the workspace.
    Gradient emails them a sign-in link. This is the default path, and the one to use unless you
    have a reason not to.
  </Step>

  <Step title="By email domain (auto-join)">
    Turn on auto-join and list your company domains. Anyone who signs in with a matching email
    address joins your organization with the **reviewer** role, with no invitation.
  </Step>

  <Step title="Through your identity provider">
    With SSO or SCIM, your identity provider decides who has access and what role they hold.
    See [Members and permissions](/docs/concepts/members-and-permissions).
  </Step>
</Steps>

### Set up auto-join

Auto-join is off by default, and only an **owner** can change it, because it decides who gets into
your workspace. To turn it on, go to **Settings, Team**, then **Auto-join by email domain**. Add
each domain you own, for example `acme.com`. Gradient rejects two kinds of entry:

* **Generic email providers** such as `gmail.com` or `outlook.com`. Allowing one would let any
  account at that provider into your workspace.
* **Malformed domains**. Enter the domain only, without `@`, `https://`, or a path.

<Warning>
  Anyone who joins this way can read every candidate report in the workspace. Only list domains
  you control, and check the member list after you turn it on. If your organization enforces
  SSO, leave auto-join off: it is a second way in, and it defeats the enforcement.
</Warning>

You cannot turn auto-join on with an empty domain list. A rule that allows nothing is a rule
that does nothing, so Gradient asks for at least one valid domain first.

## How candidates get in

A candidate never creates an account, sets a password, or holds a role. Their invitation email
contains an **assessment link**, and that link is the credential.

| Property      | Behavior                                                                                                      |
| ------------- | ------------------------------------------------------------------------------------------------------------- |
| Scope         | One link works for one assessment session only.                                                               |
| Guessability  | The token in the link is random and cannot be guessed.                                                        |
| Lifetime      | The link stays valid until the session is submitted. It has no fixed expiry date.                             |
| Sign-in state | Opening the link starts a 24-hour workspace session. If it runs out, the candidate opens the same link again. |
| Concurrency   | A candidate can hold more than one open session in the same browser. The sessions do not collide.             |
| Reuse         | Once the session is submitted, the link stops working and shows a "completed" message.                        |

Because the link is the credential, treat it like a password: send it to the candidate only, and
use **Resend** rather than forwarding an old email if they need a new one.

<Note>
  You can open a candidate's link yourself in review mode to see what they saw. Gradient
  recognizes you as a signed-in member of the assessment's organization and opens the session
  read-only. It does not sign you in as the candidate, and it does not change their session.
</Note>

## API keys

An API key is a machine credential, not a member. It acts for your whole organization, it does
not appear on **Settings, Team**, and it is not tied to a person, so it keeps working after that
person leaves. Use it to read and write assessment data from your own systems. See
[Managing API keys](/docs/guides/managing-api-keys) for how to create and rotate one.

Requests with an API key are rate limited to **300 requests per minute** by default. A request
over the limit gets a `429` response with a `Retry-After` header.

## Related

<CardGroup cols={2}>
  <Card title="Members and permissions" icon="users" href="/docs/concepts/members-and-permissions">
    The four roles, what each one can do, and how roles are assigned.
  </Card>

  <Card title="Managing API keys" icon="key" href="/docs/guides/managing-api-keys">
    Create, scope, and rotate the keys that call the Gradient API.
  </Card>
</CardGroup>