Authorize

Authorize

#340440

Description

The authorize resource is used to obtain a JSON Web Token (JWT) for Densify users to make authorized API requests. The resource will return a token for any active Densify user when the proper credentials are provided. Only API-enabled users can make authorized API calls. See Using the API: Authentication for details on API-enabled users.

The JWT API token is only valid within the expiry time of the token, which by default is set to 5 minutes.

The key used to validate the token is also refreshed every 30 days.

Security Considerations

The authorization workflow provides a progressively longer delay each time an invalid password is entered in an Authorize request.

This behaviour is applied regardless of whether or not you have enabled the Densify password policy. The workflow does change if the password policy has been enabled. Contact [email protected] for details.

Contact [email protected] for details on configuring the Densify password policy.

Resource

/authorize

Supported Operations

Table: Authorize Supported Operations

Operation

HTTP Method

Input

Output

Description

Obtain a JWT API token

POST /authorize

Request Body Parameters:

Used to return an API token for an active Densify user.

Example: Successful Authorize

Example: Unauthorized

Parameters

Request Body Parameters

Table: Authorize Request Body Parameters

Parameter Name

Type

Description

userName

string

The username of an active Densify user account.

For API access, the Densify user must be part of the Administrator or SaaS_User user group. See Using the API: Authentication for details on API-enabled users.

The /authorize resource will return a token for any active Densify user with proper credentials provided, however, only tokens for API-enabled users can be used to make authorized API calls.

pwd

string

The corresponding password for userName.

Note:  Densify highly recommends using an SSL web service to ensure that user credentials are encrypted. Contact [email protected] for details.

Response

The following is a list of possible response elements that are returned for the /authorize resource. If authorization failed, two elements are returned:

Table: Authorize Response Schema

Element

Type

Sort By

Filter

Description

apiToken

string

 

 

The returned token used to make subsequent authorized API calls. The API token follows the JSON Web Token (JWT), RFC 7519 standard.

Specify the Bearer authorization type with the token in the header of subsequent API requests:

Authorization: Bearer <apiToken>

See Example: Using Authorize JWT Token.

expires

number

 

 

The date and time (in milliseconds) when the apiToken expires.

status

number

 

 

The HTTP response code of the request. Possible status values include:

  • 200—successful response;
  • 400—the payload is null or invalid (i.e. userName or pwd is empty or invalid);
  • 401—authentication failed (e.g. user does not exist, incorrect password, or user account is locked).
  • 403—forbidden access. The trial or subscription has expired.
  • 429—requests are too frequent.
  • 500—internal server error.

message

string

 

 

The message for an error status response. See the row above, for details

Note:  Other response status and error messages could indicate issues with the Densify web server or connectivity issues to the web server.

Examples

Example: Successful Authorize

The following example shows you how to obtain an API token using the apiUser account.

Request:

Copy 
POST /authorize
{
    "userName": "apiUser",
    "pwd": "apiPassword"
}

Response:

Copy 
{
  "apiToken": "eyJhbGciOiJIUzUxMiJ9.eyJqdGkiOiIzNzI2Yzk0NC0wMmE4LTRlYzQtOGE2Ny04ODBmMDM2OTRhZDciLCJpYXQiOjE1NDI2NTI0MDUsInN1YiI6InZhbiIsImlzcyI6IkRlbnNpZnkuY29tIiwiZXhwIjoxNTQyNjUyNzA1fQ.cJd8qFJfRoPnMEU7GzcdYGBT8WwlgmviQ1OQp8P_w9VUcjQA3FJaB9QkqJJ6d7zbrY5yjc4w0rOWjY-PPdbmqw",
  "expires" : 1542652705869,
  "status" : 200
}

Example: Unauthorized

The following example shows an authorize request with invalid user credentials.

Request:

Copy 
POST /authorize
{
    "userName": "APIUser",
    "pwd": "wrongPassword"
}

Response:

Copy 
{
  "message" : "Unauthorized",
  "status" : 401
}

Example: Using Authorize JWT Token

The following example shows you how to use the API token obtained from the /authorize resource to make an authorized API request. In this example, an API request is made to list all cloud analyses in Densify using the JWT token for authorization, which is passed to the header as a Bearer token authorization type.

Request:

Copy 
GET /analysis/cloud

Headers:

Copy 
Accept: application/json 
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJqdGkiOiIzNzI2Yzk0NC0wMmE4LTRlYzQtOGE2Ny04ODBmMDM2OTRhZDciLCJpYXQiOjE1NDI2NTI0MDUsInN1YiI6InZhbiIsImlzcyI6IkRlbnNpZnkuY29tIiwiZXhwIjoxNTQyNjUyNzA1fQ.cJd8qFJfRoPnMEU7GzcdYGBT8WwlgmviQ1OQp8P_w9VUcjQA3FJaB9QkqJJ6d7zbrY5yjc4w0rOWjY-PPdbmqw

Note:  The long JWT token string is taken from the apiToken element of an /authorize request. This example shows the raw token string, but typical implementations would save the API token as a variable and pass it to the request header. See Example: Returning AWS Recommendations with Low Effort in Terraform-map Form.