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.

Hint: Users must have admin permissions to create access tokens. Admin users can create access tokens for themselves as well as other users.

Create an Access Token

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

  2. For the appropriate user, select Edit tokens from the More drop-down menu.

  3. Enter a token name, then click Create Token.

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

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

Apply an Access Token

You can use the 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 literal string token in place of the password: YourToken:token.

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

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

In the above code, be sure to insert your own generated access token in place of the example shown.

Delete an Access Token

Generated access tokens do not expire. When you no longer need an access token, you should delete it via the Users Overview page:

  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.

Warning: You cannot undo the delete token action. After an access token is deleted, it will not be recognized for authentication by the REST API. If the deleted token is used in any scripts, you will need to update those references with a new, valid token.

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 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:

Copy 
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:

{

"valid_until" : "2024-07-18T01:30:25.670+0000",

"session_id" : "84fd7d9-587d-4687-830ce-01a3f365e1a8"

}

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:

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