Authenticate (POST /v3/auth/tokens)

Authenticates an identity and generates a token.

Delete control characters such as carriage returns from the generated token, and specify it in the X-Auth-Token request header of each API (refer to the end of this section for an example)

If consecutive password errors exceeding the threshold (5 times) are detected within a certain period of time (15 minutes), an authentication error will occur for a certain period (15 minutes), during which time it will not be possible to perform authentication.

Request headers

Content-type

Indicates the format of content defined in the MIME specification.

Specify application/json. (required)

Data type Cardinality
xsd:string 1..1

Accept

Indicates the accept format defined in the MIME specification.

Specify application/json. (optional)

Data type Cardinality
xsd:string 1..1

Request parameters

auth

auth object (required)

Data type Cardinality Parent element Child element
Element 1..1 None identity

scope

identity

identity object (required)

Data type Cardinality Parent element Child element
Element 1..1 auth methods

password

token

saml2

methods

Authentication method (required)
  • Specify either password authentication or token authentication
Input value
  • password: Password authentication
  • token: Token authentication
Data type Cardinality Parent element Child element
xsd:string 1..1 identity None

password

password object (required when using password authentication)

Specify when using password authentication.

Perform authentication using one of the following combinations:
  • User ID and password
  • Domain ID, user name, and password
  • Domain name, user name, and password
Data type Cardinality Parent element Child element
Element 0..1 identity user

user

user object (required when using password authentication)

Specify an ID or name to uniquely identify the user and password.

Data type Cardinality Parent element Child element
Element 0..1 password domain

id

name

password

domain

domain object

Data type Cardinality Parent element Child element
Element 0..1 user id

name

id

Domain ID

Data type Cardinality Parent element Child element
xsd:string 0..1 domain None

name

Domain name

Data type Cardinality Parent element Child element
xsd:string 0..1 domain None

id

User ID

Data type Cardinality Parent element Child element
xsd:string 0..1 user None

name

User name

Data type Cardinality Parent element Child element
xsd:string 0..1 user None

password

Password (required when using password authentication)

Data type Cardinality Parent element Child element
xsd:string 0..1 user None

token

token object (required when using token authentication)

Specify when using token authentication.

Data type Cardinality Parent element Child element
Element 0..1 identity id

id

Authenticated token (required when using token authentication)

Data type Cardinality Parent element Child element
xsd:string 0..1 token None

scope

scope object

Specify ID or name to uniquely identify the domain or project.

When project is specified in the scope parameter, the project ID is not mandatory, and it is possible to retrieve a token with the project name. However, additional parameters are necessary when using the project name. When project is specified for scope, the required parameter varies depending on the parameter specified for project.
  • When specifying a project ID for the parameter specified in project

    In the following, only the ID of the project is specified.

    {"scope":{"project":{"id":"--project-id--"}}}

  • When specifying a project name for the parameter specified in project

    As a token cannot be retrieved with only the project name, it is necessary to add the domain parameter as well as the project name.

    Specify id or name for the domain parameter
    • Example of Project name + Domain ID:
      {"scope":{"project":{"name":"--project-name--","domain":{"id":"--domain-id--"}}}}
    • Example of Project name + Domain name:
      {"scope":{"project":{"name":"--project-name--","domain":{"name":"--domain-name--"}}}}

If performing token authentication, specify trust.

If this element is omitted, the result will be the same as specifying a project.

Also, if this element is specified in the wrong location in the request, it may be ignored.

Data type Cardinality Parent element Child element
Element 0..1 auth project

domain

OS-TRUST:trust

project

project object

Data type Cardinality Parent element Child element
Element 0..1 scope domain

id

name

domain

domain object

Data type Cardinality Parent element Child element
Element 0..1 project id

name

id

Domain ID

Data type Cardinality Parent element Child element
xsd:string 0..1 domain None

name

Domain name

Data type Cardinality Parent element Child element
xsd:string 0..1 domain None

id

Project ID

Data type Cardinality Parent element Child element
xsd:string 0..1 project None

name

Project name

Data type Cardinality Parent element Child element
xsd:string 0..1 project None

domain

domain object

Data type Cardinality Parent element Child element
Element 0..1 scope id

name

id

Domain ID

Data type Cardinality Parent element Child element
xsd:string 0..1 domain None

name

Domain name

Data type Cardinality Parent element Child element
xsd:string 0..1 domain None

OS-TRUST:trust

OS-TRUST:trust object

Data type Cardinality Parent element Child element
Element 0..1 scope id

id

Trust ID

Data type Cardinality Parent element Child element
xsd:string 0..1 OS-TRUST:trust None

Response headers

HTTP status code

Returns the HTTP status code of the request.

One of the following values will be returned.

201:
Normal completion
400:
Invalid access (invalid parameter, etc.)
401:
Authentication error
403:
Cannot access (no privileges)
404:
No applicable resources
409:
Data conflict occurred
500:
Unexpected error
501:
Has not been implemented
503:
Cannot use service
Data type Cardinality
int 1..1

Vary

By setting or changing the following header, notification is given that expressions can be requested in a different file format.

X-Auth-Token

Data type Cardinality
xsd:string 1..1

Content-Type

Indicates the format of content defined in the MIME specification.

application/json

Data type Cardinality
xsd:string 1..1

Content-Length

Indicates the length of an entity in bytes.

Data type Cardinality
int 1..1

Date

Indicates the date when the request was created.

Data type Cardinality
date 1..1

X-Subject-Token

Token (Unscoped token or Scoped token)

Data type Cardinality
xsd:string 1..1

Response elements

token

token object

Data type Cardinality Parent element Child element
Element 1..1 None expires_at

issued_at

methods

roles

domain

project

catalog

extras

user

expires_at

Token expiry datetime

Data type Cardinality Parent element Child element
xsd:string 1..1 token None

issued_at

Token issue datetime

Data type Cardinality Parent element Child element
xsd:string 1..1 token None

methods

Authentication method

Data type Cardinality Parent element Child element
xsd:string 1..1 token None

roles

roles object

Data type Cardinality Parent element Child element
Element 0..1 token (role)

(role)

role object (object name is not displayed)

Data type Cardinality Parent element Child element
Element 1..n roles id

name

id

Role ID

Data type Cardinality Parent element Child element
xsd:string 1..1 (role) None

name

Role name

Data type Cardinality Parent element Child element
xsd:string 1..1 (role) None

domain

domain object

This is set when a domain is specified for scope.

Information about the domain that was specified for scope

Data type Cardinality Parent element Child element
Element 0..1 token id

name

id

Domain ID

Data type Cardinality Parent element Child element
xsd:string 0..1 domain None

name

Domain name

Data type Cardinality Parent element Child element
xsd:string 0..1 domain None

project

project object

This is set when a project is specified for scope.

Information about the project that was specified for scope

Data type Cardinality Parent element Child element
Element 0..1 token domain

id

name

domain

domain object

Data type Cardinality Parent element Child element
Element 0..1 project id

name

id

Domain ID

Data type Cardinality Parent element Child element
xsd:string 0..1 domain None

name

Domain name

Data type Cardinality Parent element Child element
xsd:string 0..1 domain None

id

Project ID

Data type Cardinality Parent element Child element
xsd:string 0..1 project None

name

Project name

Data type Cardinality Parent element Child element
xsd:string 0..1 project None

catalog

catalog object

Data type Cardinality Parent element Child element
Element 0..1 token endpoints

type

id

endpoints

endpoints object

Data type Cardinality Parent element Child element
Element 0..1 catalog (endpoint)

endpoint

endpoint object (object name is not displayed)

Data type Cardinality Parent element Child element
Element 1..n endpoints name

url

region

interface

id

name

Endpoint name

Data type Cardinality Parent element Child element
xsd:string 1..1 (endpoint) None

url

url information

Data type Cardinality Parent element Child element
xsd:string 1..1 (endpoint) None

region

Region name

Data type Cardinality Parent element Child element
xsd:string 1..1 (endpoint) None

interface

Interface information

Data type Cardinality Parent element Child element
xsd:string 1..1 (endpoint) None

id

Endpoint ID

Data type Cardinality Parent element Child element
xsd:string 1..1 (endpoint) None

type

Service type

Data type Cardinality Parent element Child element
xsd:string 0..1 catalog None

id

Service ID

Data type Cardinality Parent element Child element
xsd:string 0..1 catalog None

extras

Extension information

Data type Cardinality Parent element Child element
xsd:string 1..1 token None

users

users object

Data type Cardinality Parent element Child element
Element 1..1 token domain

id

name

domain

domain object

Data type Cardinality Parent element Child element
Element 1..1 user id

name

id

Domain ID

Data type Cardinality Parent element Child element
xsd:string 1..1 domain None

name

Domain name

Data type Cardinality Parent element Child element
xsd:string 1..1 domain None

id

User ID

Data type Cardinality Parent element Child element
xsd:string 1..1 user None

name

User name

Data type Cardinality Parent element Child element
xsd:string 1..1 user None

Example of request


POST /v3/auth/tokens

Example 1: Password authentication
The domain ID and user name are specified, and the scope parameter is omitted (therefore the result will be the same as if a project was specified)
{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "domain": {
                        "id": "--domain-id--"
                    },
                    "name": "username",
                    "password": "userpassword9999"
                }
            }
        }
    }
}

Example 2: Token authentication
{
    "auth": {
        "identity": {
            "methods": [
                "token"
            ],
            "token": {
                "id": "(specify the authentication token)"
            }
        },
        "scope": {
            "OS-TRUST:trust": {
                "id": "--trust_id--"
            }
        }
    }
}

Example of response


       Example: In password authentication, an example response when project information is specified in scope
       {
        "token": {
         "methods": [
          "password"
         ],
         "roles": [
          {
           "id": "—role-id--",
           "name": "admin"
          }
         ],
         "expires_at": "2013-02-27T18:30:59.999999Z",
         "project": {
          "domain": {
           "id": "--domain-id--",
           "name": "admin"
          },
          "id": "--project-id--",
          "name": "admin"
         },
         "catalog": [
          {
           "endpoints": [
            {
             "name": "identityv3",
             "url": "https://identity.jp-east-1.cloud.global.fujitsu.com/v3",
             "region": "jp-east-1",
             "interface": "public",
             "id": "--endpoint-id--"
            }
           ],
           "type": "identityv3",
           "id": "--service-id--"
          },
. . .
          {
           "endpoints": [
            {
            "name": "image",
            "url": "https://image.jp-east-1.cloud.global.fujitsu.com",
            "region": "jp-east-1",
            "interface": "public",
            "id": "--endpoint-id--"
            }
            "type": "image",
            "id": "--service-id--"
          }
         ],
         "extras": {},
          "user": {
           "domain": {
            "id": "--domain-id--",
            "name": "admin"
           },
           "id": "--user-id--",
           "name": "username"
          },
          "issued_at": "2013-02-27T16:30:59.999999Z"
         }
        }

Example of using curl command to delete carriage returns from end of token


export TOKEN=`curl -si -H "Content-Type:application/json" -d @data.json
http://xxxxx/v3/auth/tokens | awk '/X-Subject-Token/ {print $2}' | tr -d "\r"`