Bare metal server identity access token concepts

A bare metal server identity access token provides a security credential for accessing the metadata service. It's a signed token with a set of claims based on information about the bare metal server and information that is passed in the token request.

To access the bare metal server identity, make a PUT "http://api.metadata.cloud.ibm.com /identity/v1/token call by using the Metadata service API that invokes the bare metal server hostname. Communication between the bare metal server and metadata service never departs the host. You acquire the token from within the bare metal server. If secure access to the bare metal server metadata service is enabled on your bare metal server, use the https protocol instead of the http protocol.

In the request, you specify an expiration time for the token. The default is 5 minutes, but you can specify that it expires sooner or later (5 seconds to 1 hour).

The response (a JSON payload) contains the bare metal server identity access token. Use this token to access the metadata service.

You can also generate an IAM token from this token and use the API to call IAM-enabled services. For more information, see Generate an IAM token from a bare metal server identity access token.

Acquiring a bare metal server identity access token

Using the Metadata service API, make PUT "http://api.metadata.cloud.ibm.com /identity/v1/token call to get a bare metal server identity access token. The following example uses jq to parse the JSON API response and then extract the bare metal server identity access token value. You can use your preferred JSON parser.

In the example, the return value of the CURL command is the bare metal server identity access token, which is extracted by jq and placed in the identity_token environment variable. You use specify this variable in a GET call to the metadata service to reach the metadata endpoint. For more information, see Retrieve metadata from your running bare metal server.

The example uses jq as a parser, a third-party tool licensed under the MIT license. jq might not come preinstalled on all VPC images available when you create a bare metal server. You might need to install jq before use or use any parser of your choice.

identity_token=`curl -X PUT "http://api.metadata.cloud.ibm.com /identity/v1/token?version=2025-06-30"\
  -H "Metadata-Flavor: ibm"\
  -d '{
        "expires_in": 3600
      }' | jq -r '(.access_token)'`

The following JSON response shows the bare metal server identity access token character string, date, and time that it was created, date, and time that it expires, and expiration time you set. Keep in mind that the token expires in 5 minutes.

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IlZTSS1DUl91cy1lYXN0X2I5...",
  "created_at": "2022-08-08T11:08:39.363Z",
  "expires_at": "2022-08-08T11:13:39.363Z",
  "expires_in": 3600
}