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

# Authentication

> Learn how to authenticate to the Endor Labs REST API.

## About Authentication

Endor Labs supports multiple authentication methods. In all cases, clients use an Endor Labs specific API token to exchange their identity with Endor Labs. The token uses x509 signatures, and the Endor Labs private key signs it.

You can initiate the authentication process through the authentication methods described below. The API authenticates the client and returns an Endor Identity Token (`ENDOR_TOKEN`) that it can apply to all its requests. The token validity depends on the authentication providers' [session duration](/platform-administration/rbac/authentication-providers#session-duration).

After creating an API token, you can authenticate your requests by including the token in the Authorization header. For example, you can export it using the `ENDOR_TOKEN` variable and then use it in curl commands such as the following.

If needed, replace `$ENDOR_NAMESPACE` with the name of your namespace.

```bash theme={null}
curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/projects" \
```

<Note>
  Basic authentication with curl -u is not supported.
</Note>

The following sections describe the different ways you can create an `ENDOR_TOKEN`.

## Headless mode

1. Paste the following URL in your preferred browser:

   <Tabs>
     <Tab title="Google">
       ```bash theme={null}
       https://api.endorlabs.com/v1/auth/google?redirect=headless
       ```
     </Tab>

     <Tab title="GitHub">
       ```bash theme={null}
       https://api.endorlabs.com/v1/auth/github?redirect=headless
       ```
     </Tab>

     <Tab title="GitLab">
       ```bash theme={null}
       https://api.endorlabs.com/v1/auth/gitlab?redirect=headless
       ```
     </Tab>

     <Tab title="Email">
       ```bash theme={null}
       https://api.endorlabs.com/v1/auth/login?email=<my_email>&redirect=headless
       ```
     </Tab>

     <Tab title="SSO">
       ```bash theme={null}
       https://api.endorlabs.com/v1/auth/sso?tenant=<my_namespace>&redirect=headless
       ```
     </Tab>
   </Tabs>

2. Use your browser window to authenticate

3. If authenticating with email, follow the link sent to the provided email

4. Once authenticated, copy the token displayed by the browser

5. Go back to your terminal and export it to your `ENDOR_TOKEN` environment variable

## API key and secret

This method provides authentication using Endor Labs API keys. Any user of the system can create an API key under a namespace. The key consists of a key and a secret randomly generated by the system.

### Using endorctl

If you [authenticate with Endor Labs using endorctl](/developers-api/cli/commands/init), it creates a `~/.endorctl/config.yaml` file in your environment containing essential details such as the API key, secret, and tenant namespace.

Use the following command to export the value of your access token:

```bash theme={null}
export ENDOR_TOKEN=$(endorctl auth --print-access-token)
```

### Using the Endor Labs user interface

Generating an API key and secret using the Endor Labs user interface enables you to select a custom expiration date and permissions.

To generate an API key and secret via the Endor Labs user interface, follow these steps:

1. On the left sidebar, select **Settings** > **Access Control** from the left sidebar, then select **API Keys**.
2. Click **Generate API Key**.
3. Specify the following key details:
   * **Name:** Enter a descriptive name for the API key, identifying its purpose or user.
   * **Permission Level:** Choose the appropriate permission level for the API key. Options include:
     * **Admin:** Full access to all features and functionalities.
     * **Read-only:** View-only access, without the ability to modify or create resources.
     * **Code Scanner:** Access specifically for code scanning functionalities.
     * **Policy Editor:** Access to policy editing features.
     * **On-Prem Scheduler:** Access to manage [Outpost](/setup-deployment/outpost) and to use [monitoring scans](/setup-deployment/scm-integrations) across supported platforms when you enable Outpost.
4. Select the desired expiry date for the API key, ranging from 30 to 90 days.
5. Click **Generate API Key** for confirmation.

Under the **Advanced** section, you have the option to propagate the API key to all child namespaces.

After generating your API key and secret, click **Copy API Key & Secret**. Make sure to securely store your API secret in a safe location, as it will not be accessible through the Endor Labs user interface later.

The copied key and secret will look like this:

```bash theme={null}
# Endor API Key: name
# Expires: 2024-09-05T00:06:16.789Z
ENDOR_API_CREDENTIALS_KEY=endr+foo
ENDOR_API_CREDENTIALS_SECRET=endr+bar
```

You can then get a token by making a `POST` request with the API key and secret to the `https://api.endorlabs.com/v1/auth/api-key` endpoint.

<Tabs>
  <Tab title="curl">
    The response contains both the token and the expiration time, so use `jq` to extract the token and export it directly to the `ENDOR_TOKEN` environment variable:

    ```bash theme={null}
    export ENDOR_TOKEN=$(curl --request POST \
      --url "https://api.endorlabs.com/v1/auth/api-key" \
      --data '{ "key": "$ENDOR_API_CREDENTIALS_KEY", "secret": "$ENDOR_API_CREDENTIALS_SECRET" }' \
      | jq -r .token)
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    @baseUrl = https://api.endorlabs.com

    ###
    POST {{baseUrl}}/v1/auth/api-key
    content-type: application/json

    {
      "key" : "endr+foo", "secret":"endr+bar"
    }
    ```
  </Tab>
</Tabs>

## Authentication precedence

If you have set up multiple ways to authenticate endorctl, the precedence is as follows:

1. **Arguments in the endorctl command**

   You can provide [authentication information in the endorctl command](/developers-api/cli/commands/init), and these credentials take the highest precedence during authentication. Even if authentication information is available in the `~/.endorctl/config.yaml` file or the `ENDOR_TOKEN` environment variable, the value you provide in the command takes precedence.

2. **Authentication information in `~/.endorctl/config.yaml`**

   If you [authenticate with Endor Labs using endorctl](/developers-api/cli/commands/init), the `~/.endorctl/config.yaml` file is created in your environment that contains authentication information (such as API key and tenant namespace). Even if you set a different authentication token as the `ENDOR_TOKEN` environment variable, the information in the `~/.endorctl/config.yaml` file takes precedence.

3. **ENDOR\_TOKEN environment variable**

   If you do not provide authentication information in the endorctl command or if there is no authentication information in the `~/.endorctl/config.yaml` file, the authentication information specified in the `ENDOR_TOKEN` environment variable is used for authentication. To use the `ENDOR_TOKEN` variable, ensure that neither the command-line arguments nor the `~/.endorctl/config.yaml` file contain authentication information.

## Failed authentication

If you try to use a REST API endpoint without an Endor Labs token, you will receive a 401 Unauthorized response. For more information, see [troubleshooting](/developers-api/rest-api/using-the-rest-api/troubleshooting).