Skip to content


The Keystash API makes use of Authorization Bearer Tokens. Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The name “Bearer authentication” can be understood as “give access to the bearer of this token.” The bearer token is a cryptic string, usually generated by the server in response to a login request. The client must send this token in the Authorization header when making requests to protected resources:

Authorization: Bearer <token>

The Bearer authentication scheme was originally created as part of OAuth 2.0 in RFC 6750, but is sometimes also used on its own. Bearer authentication should only be used over HTTPS (SSL).

Authentication is carried out with a normal Keystash users account. The permissions granted in Keystash apply to the API in the same. Therefor if a user does not have access to Server Groups inside Keystash, then they won't have access to Server Groups via the API. We suggest you create a separate user account for integration utilising the API. This way your integration doesn't stop working if the user account is removed.


Path: /login

Method: POST

Request Headers

Param Value Required
Accept-Encoding gzip optional

Request Body

Key Value Notes
username urlencoded
password mySecurePassword urlencoded


Use your Keystash username (email address) and password to login.

Example Request

curl --location --request POST '' \
--header 'Accept-Encoding: gzip' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode '' \
--data-urlencode 'password=mySecurePassword'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

  "authenticated": true,
  "token": "vyJhbGciOiJIUzI1NiIsInR5cCI6kpXVCJ9.eyJzZXNzaW9uX2lkIjoiSXNwTDNnYlVFeS1QWlFvb2JnWFItYUd1ck9jTXAyLXMiLCJpYXQiOjE2NjQyODY4OTcsImV4cCI6MTY2NDMzMertterNywiYXVkIjoiYXBwLmtleXN0YXNoLmlvIiwiaXNzIjoiYXBwLmtleXN0YqNoLmlvIn0.m2cXsqIjFlxHwW2_Jxz9bgwxxyXrOzpIyGIxyEyAOFg",
  "message": "Authentication successful."

Example Error Response

HTTP/1.1 403
Content-Type: application/json; charset=utf-8

  "error":"The authentication credentials were not valid. Please re-authenticate with the correct username and password."


The token will need to be supplied with each API request as the authentication token. The token is valid for 1 hour and you will need to re-authenticate once it has expired.

Example Permission Error Response

HTTP/1.1 403
Content-Type: application/json; charset=utf-8

  "error": {
    "code": "Forbidden",
    "message": "You do not have the required permission to access this path.",
    "details": [
        "path": "/api/v1/servers/list"