Authentication

About Authentication

Endor Labs supports several methods of authentication. In all cases, clients use an Endor Labs specific API token to exchange their identity with Endor Labs. The token uses x509 signatures and is signed by the Endor Labs private key.

The authentication process is initiated by the caller via one of 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 and is valid for 4 hours.

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.

curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/projects" \

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

Headless mode

1. Paste the following URL in your preferred browser:

   • Google
   • GitHub
   • GitLab
   • Email
   • SSO

   https://api.endorlabs.com/v1/auth/google?redirect=headless
   

   https://api.endorlabs.com/v1/auth/github?redirect=headless
   

   https://api.endorlabs.com/v1/auth/gitlab?redirect=headless
   

   https://api.endorlabs.com/v1/auth/login?email=<my_email>&redirect=headless
   

   https://api.endorlabs.com/v1/auth/sso?tenant=<my_namespace>&redirect=headless
   

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 then a ~/.endorctl/config.yaml file is created 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:

export ENDOR_TOKEN=$(endorctl auth --print-access-token)

Using the UI

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 UI, follow these steps:

1. On the left sidebar, navigate to the Access Control section, and 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.
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 UI later.

The copied key and secret will look like this:

# 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.

• curl
• HTTP

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)

@baseUrl = https://api.endorlabs.com

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

{
  "key" : "endr+foo", "secret":"endr+bar"
}

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, 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, 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.