REST API Access Tokens

Graylog allows you to create access tokens that can be used for REST API authentication. All requests to the API must be authenticated with valid user credentials. However, for security reasons, sending the username and password directly over the command line or in some third-party applications is not recommended. Use an access token to avoid the use of clear-text credentials.

Create an Access Token

To create a new API access token:

1. Navigate to System > Users and Teams to view the Users Overview page.

2. Locate the user in the list, then select Edit tokens from the More drop-down menu.

3. Enter a token name.

   Hint: If you create multiple tokens per user, be sure to assign unique names that describe each token’s purpose.

4. Enter a value for the token time to live (TTL). The default value is 30 days. Tokens generated for built-in system users, such as the Graylog Forwarder, default to 100 years. You can set this value to a shorter duration if desired.

   Hint: You set this value using the conventions for durations from the ISO 8601 standard.

5. Click Create Token.

6. Copy the generated token and save it in a secure location for use in your API calls.

   Warning: You cannot retrieve the access token if you do not copy it from the pop-up window. If a token is lost or forgotten, you must create a new one.

You should now see the token in the user's token list. The token is also added to the table on the Token Management tab.

Apply an Access Token

You can use a valid access token for API access at the command line. In a request to the Graylog REST API using HTTP Basic authentication, you use your token in place of a username and the string token in place of the password: YourToken:token.

Using the access token, the following curl command retrieves information about Graylog clusters including the example token ccg6i59gk1db4jeqed2di1qetlh5g21423j93esom4q8lelbj42:token:

curl -u ccg6i59gk1db4jeqed2di1qetlh5g21423j93esom4q8lelbj42:token -H 'Accept: application/json' -X GET 'http://localhost:9000/api/cluster?pretty=true'

Manage Access Tokens

To view and manage all current access tokens, navigate to System > Users and Teams, then select the Token Management tab. The table shows the username of the token's owner along with other relevant information such as the token creation and expiration date/time and whether the user is internal (manually created on the Graylog system) or external (imported via a third-party identity source).

You can sort the table by column headers to view relevant information. You can find specific users or tokens by using search, which can be useful when you have many active tokens. By default, the search field looks only in the Token Name column. You can target other columns with the syntax columnName:searchTerm. For example, username:bob filters the list to any user with bob as part of their username.

Delete an Access Token

When you no longer need an access token, you should delete it as a security best practice. You can delete any token from the Token Management tab of the Users and Teams page:

1. Locate the token you want to delete in the list.

2. Click Delete in the Action column.

3. Click Confirm in the pop-up dialog box.

You can also delete tokens for specific users from the Users Overview tab of Users and Teams:

1. Select Edit token from the More drop-down menu for the correct user.

2. Click Delete for the access token you want to remove in the list of tokens.

Set Access Token Defaults

You can adjust configuration settings for several settings related to access tokens. Navigate to System > Configurations, then select the Users tab.

The following settings apply to access tokens:

• Allow users to create personal access tokens: Select this setting to allow creation of personal access tokens by regular users as well as administrators.

• Allow access token for external users: Select this option to allow external users to create access tokens. An external user is one who is imported via a third-party identity source. Note that prohibiting external users applies only to the ability to create tokens. You can still create tokens for external user, which they can use.

  Hint: If Allow access token for external users is not selected, any external user with the Admin role is still eligible to create tokens.

• Default TTL for new tokens: Set the default value for TTL to apply to new tokens. This value appears in the field when you create a new token. Note, however, that you can change the value during creation for specific tokens.

Create and Apply Session Tokens

While access tokens are generally the best method for secure command line access to the REST API, you might have use cases for a session token. The limited session token has some key differences:

• Session tokens expire after a set time. The expiration time can be adjusted in the user’s profile.

• Session tokens are created only via the command line, not through the Graylog UI.

You create a session token by using a POST request to the Graylog REST API. Your username and password are required to get a valid session ID. The following example creates a session token for the user bobby:

curl -i -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'X-Requested-By: cli' -X POST 'http://localhost:9000/api/system/sessions'?pretty=true -d '{"username":"bobby", "password":"superSecretPW", "host":""}'

The response includes the session token in the field session_id and the expiration time in valid_until:

You can use the session token as the username in a request to the Graylog REST API using Basic Auth together with the literal password session: SessionToken:session.

Using the session token, the following curl command retrieves information about Graylog clusters:

curl -u 84fd7d9-587d-4687-830ce-01a3f365e1a8:session -H 'Accept: application/json' -X GET 'http://localhost:9000/api/cluster?pretty=true'

• REST API

• REST API Use Cases

• Users and Teams