Authentication

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.

Info

The API does not make use of single sign-on, if this is enabled for your company. If you use single sign-on (SSO) and want to make use of the API, you will need to create a user that does not use single sign-on. To do this, create a user in Keystash, click Save and when prompted select Username and Password. This user can then be used to authenticate with the API.

Path: `/login`

Method: `POST`

Request Headers

Param	Value	Required
`Accept-Encoding`	gzip	optional

Request Body

Key	Value	Notes
`username`	max@example.org	urlencoded
`password`	mySecurePassword	urlencoded

Note

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

Example Request

curl --location --request POST 'https://app.keystash.io/api/v1/login' \
--header 'Accept-Encoding: gzip' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=max@example.org' \
--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."
}

Note

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"
      }
    ]
  }
}

Authentication

Login

Path: /login

Method: POST