IBM Cloud API Docs

Introduction

The IBM Cloud® Virtual Private Cloud (VPC) Identity API provides methods through the VPC Metadata service to retrieve resources, such as certificates and access tokens for the calling identity. Tokens eliminate the risk of accidental exposure of API keys, passwords, and long-lived access tokens used by automation on bare metal servers. The Identity API includes support for virtual server instances and bare metal servers.

You can generate an IAM token from an identity token to gain access to virtual server instances or bare metal servers. If an IBM Cloud Identity and Access Management (IAM) trusted profile is used to establish a trust relationship with the virtual server instance, the Identity API provides the ability for the virtual server instance to get access tokens for other IAM-enabled cloud services, such as API Connect, Event Streams, Secrets Manager, and Cloud Object Storage.

Endpoint URLs

Access to the VPC Metadata service is disabled on bare metal servers and virtual server instances by default. You can enable the Metadata service when creating or updating an instance or when creating or updating a bare metal server.

The Metadata service can be accessed from within the virtual server instance or bare metal server using an endpoint URL:

  • When the metadata_service.protocol property is http (unencrypted), the endpoint URL may contain either the service's IP address http://169.254.169.254 or the service's hostname http://api.metadata.cloud.ibm.com.
  • When the metadata_service.protocol property is https, the endpoint URL must contain the service's hostname https://api.metadata.cloud.ibm.com.

You cannot configure the metadata service with both http and https protocols at the same time.

When the metadata_service.enabled property is false, the Metadata API is not available. Requests sent to any of the endpoint URLs will receive no response.

This example stores the metadata service's hostname api.metadata.cloud.ibm.com in a vpc_identity_api_endpoint variable.

vpc_identity_api_endpoint=http://api.metadata.cloud.ibm.com

Authentication

To start an authenticated session, create an identity token and pass that token to the create identity certificate method. Alternatively, you can pass that token to the create IAM token method, and then use that token to access IAM-enabled services. Access to the VPC Metadata service API is inaccessible from outside virtual server instances or bare metal servers. For more information, see Configure the metadata service and the examples on this page.

A session lasts for the lifetime of the token, during which the service can be called. You can reuse a single access token for multiple API requests, as long as the token has not expired.

These examples use jq as a parser, a third-party tool licensed under the MIT license. You might need to install jq. Alternatively, use any parser of your choice.

Consider storing the metadata endpoint in a variable. For more information, see Configure the metadata service.

This example extracts the access token value and places it in the identity_token environment variable.

identity_token=`curl -X PUT   "$vpc_identity_api_endpoint/identity/v1/token?version=2025-08-26&generation=2"   -H "Metadata-Flavor: ibm"   -H "Accept: application/json"   -d '{           "expires_in": 300       }' | jq -r '(.access_token)'`

Example response from the previous request:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IlZTSS1DUl91cy1lYXN0X2I5MmI0YzAxNWJhOTc4NzgiLCJ....",
  "created_at": "2025-08-26:08:39.363Z",
  "expires_at": "2025-08-26:13:39.363Z",
  "expires_in": 300
}

Pass the access token in the Authorization header to authenticate Metadata requests. Tokens authenticate requests without embedding service credentials in every request. See the methods in this API reference for examples using $identity_token.

This example uses the identity_token environment variable from the previous example to create an IAM token associated with the specified trusted profile ID. Upon success, provide the iam_token environment variable when calling any IAM-enabled IBM service to perform operations using the authorizations granted to that trusted profile. Learn more about Creating trusted profiles.

iam_token=`curl -X POST   "$vpc_identity_api_endpoint/identity/v1/iam_tokens?version=2025-08-26&generation=2"   -H "Authorization: Bearer $identity_token"   -d '{
       "trusted_profile": {
          "id": "Profile-8dd84246-7df4-4667-94e4-8cede51d5ac5"
       }
      }' | jq -r '(.access_token)'`

Auditing

IBM Cloud services, such as IBM Cloud VPC, generate activity tracking events. Activity tracking events report on activities that change the state of resources in IBM Cloud and also report on certain activities that do not change any state, such as attempts to access and update resources. You can use the events to investigate abnormal activity and critical actions and to comply with regulatory audit requirements.

Monitor API activity within your account by using IBM Cloud Activity Tracker Event Routing, a platform service, to route auditing events to destinations of your choice. Configure targets and routes that define where activity tracking events are sent. Each time you make an API request, one or more events are generated that you can track and audit from within the Activity Tracker Event Routing service. Specific auditing event types are listed for each individual method. For more information, see About IBM Cloud Activity Tracker Event Routing and Activity tracking events for IBM Cloud VPC.

You can also use IBM Cloud Logs to visualize and alert on events that are generated in your account and routed by IBM Cloud Activity Tracker Event Routing to an IBM Cloud Logs instance. For more information, see Getting started with IBM Cloud Logs.

Error handling

This API uses standard HTTP response codes to indicate the outcome of a request. A 2xx-series response indicates success. A 4xx-series response indicates a failure that the client must resolve. A 5xx-series response indicates a service failure.

HTTP error code Description Disposition
200 Success The request was successful.
400 Bad Request The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
401 Unauthorized You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
403 Forbidden The supplied authentication is not authorized to perform the requested operation.
404 Not Found The requested resource could not be found.
408 Request Timeout The connection to the server timed out. Wait a few minutes, and try again.
500 Internal Server Error A generic error message is returned when an unexpected condition was encountered and no more specific message is suitable.
501 Not Implemented The server either does not recognize the request method, or it lacks the ability to fulfill the request. Usually this message implies future availability, such as a new feature of a web-service API.
502 Bad Gateway The server was acting as a gateway or proxy and received an invalid response from the upstream server.
503 Service Unavailable The server cannot process the request. Generally, this condition is temporary, such as when a server is overloaded or down for scheduled maintenance. This condition may also be due to an unplanned outage of a service that is needed to process the request.
504 Gateway Timeout The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.
505 HTTP Version Not Supported The server does not support the HTTP protocol version that is used in the request.

Versioning

API requests require a major version in the path (/v1/) and a date-based version as a query parameter in the format version=YYYY-MM-DD.

This reference documents API behavior for any date value in the version parameter between 2025-08-26 and today’s date. To view the reference for any other supported version of the API, select it from the Version list. For more information, see Versioning in the VPC API.

Maturity query parameter

API requests accept a maturity query parameter. This parameter lets you decide on the level of stability to use before features become generally available.

For the API behavior documented in this reference, omit the maturity query parameter. For information on making beta requests, see the Beta VPC Identity API.

This example shows how to use the HTTPS protocol to retrieve instance initialization metadata. For this example, the service must be configured with the metadata_service.protocol property set to https.

user_data=`curl -X GET   "$vpc_api_endpoint/v1/instance/initialization?version=2025-08-26"   -H "Authorization: Bearer $identity_token"   | jq -r '(.user_data)'`

Response model properties

Certain properties are included in API responses for all customer-created VPC resources. The created_at value is a timestamp that matches when the resource became visible through requests to the API.

VPC API resource conventions

See Resources the Virtual Private Cloud API to learn about resource modeling, resource names, deleted and remote resources, and resource suspension.

API best practices

To minimize bugs caused by changes, follow these best practices when you call the API:

  • Log any 4xx or 5xx HTTP status code along with the included trace property
  • Follow HTTP redirect rules for any 3xx HTTP status code
  • Use only the resources and properties that are needed for your application to function
  • Avoid depending on any behavior that is not explicitly documented

Change log

Review the change log for important changes to the VPC Identity API, such as additions, updates, and versioned changes.

Methods

Create an IAM token using an identity token

This request uses an identity token, and a trusted profile linked to a resource identity (whether the default linked at resource creation time, or one provided in the request body) to generate an IAM access token.

POST /identity/v1/iam_tokens

Auditing

Calling this method generates the following auditing event.

  • is.metadata.computeresource-token.request

Request

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2025-08-26 and 2025-08-27.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

The IAM access token prototype.

  • curl -X POST "$vpc_metadata_api_endpoint/identity/v1/iam_tokens?version=2025-08-27" -H "Authorization: Bearer $identity_token" -d '{
          "trusted_profile": {
            "id": "Profile-8dd84246-7df4-4667-94e4-8cede51d5ac5"
          }
        }'

Response

Information about this identity IAM access token

Status Code

  • The IAM access token was successfully generated.

  • An invalid IAM access token prototype object was provided.

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

Example responses
  • {
      "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aGVfYmVzdCI6IkVyaWNhIn0.c4C_BKtyZ4g78TB6wjdsX_MNx4KPoYj8YiikB1jO4o8",
      "created_at": "2021-03-22T14:10:15Z",
      "expires_at": "2021-03-22T15:10:15Z",
      "expires_in": 3600
    }
  • {
      "errors": [
        {
          "code": "profile_not_linked",
          "message": "The resource identity is not linked to the specified trusted profile",
          "more_info": "https://cloud.ibm.com/docs/vpc?topic=vpc-imd-trusted-profile-metadata",
          "target": {
            "name": "trusted_profile.id",
            "type": "field",
            "value": "Profile-dc557279-772b-4cf9-82e9-0d127c4d7ac9"
          }
        }
      ],
      "status_code": 400,
      "trace": "e37872f6-f9a4-4084-a1a8-e56a1c8c8d3d"
    }

Create an identity token

This request creates an identity token, which can be used to retrieve VPC metadata or to generate an IAM access token (using a trusted profile linked to the resource identity)

PUT /identity/v1/token

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-identity-token.create

Request

Custom Headers

  • The metadata flavor.

    Allowable values: [ibm]

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2025-08-26 and 2025-08-27.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

The identity token prototype. A valid prototype object is required even if no properties are specified.

  • curl -X PUT "$vpc_metadata_api_endpoint/identity/v1/token?version=2025-08-27" -H "Metadata-Flavor: ibm" -d '{}'

Response

The information about this access token

Status Code

  • The identity token was created successfully.

  • An invalid identity token prototype object was provided.

Example responses
  • {
      "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aGVfYmVzdCI6IkVyaWNhIn0.c4C_BKtyZ4g78TB6wjdsX_MNx4KPoYj8YiikB1jO4o8",
      "created_at": "2021-03-22T15:09:45Z",
      "expires_at": "2021-03-22T15:10:15Z",
      "expires_in": 30
    }
  • {
      "errors": [
        {
          "code": "invalid_value",
          "message": "The value provided for the `expires_in` field must be between `5` and `3600`.",
          "more_info": "https://cloud.ibm.com/docs/vpc?topic=vpc-identity#create-identity-token",
          "target": {
            "name": "expires_in",
            "type": "field",
            "value": "7200"
          }
        }
      ],
      "status_code": 400,
      "trace": "e37872f6-f9a4-4084-a1a8-e56a1c8c8d3d"
    }

Create an identity certificate using an identity access token

This request uses an identity access token, and certificate signing request, to generate an identity certificate.

POST /identity/v1/certificates

Auditing

Calling this method generates the following auditing event.

  • is.metadata.certificate.create

Request

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2025-08-26 and 2025-08-27.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

The identity certificate prototype

  • curl -X POST "$vpc_metadata_api_endpoint/identity/v1/certificates?version=2025-08-27" -H "Authorization: Bearer $identity_token" -d '{
          "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICzzCCAbcCAQAwgYkxCzAJBgNVBAYTAlVTMRIwEAYDVQQIDAlNaW5uZXNvdGEx\nEjAQBgNVBAcMCVJvY2hlc3RlcjEMMAoGA1UECgwDSUJNMR4wHAYDVQQLDBVWaXJ0\ndWFsIFByaXZhdGUgQ2xvdWQxJDAiBgNVBAMMG1ZQQyBFeGFtcGxlIEludGVybWVk\naWF0ZSBDQTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMY78TrUhSrC\nSpeLXgS4JF+PpssYQpc9kJoOTJzUPqMocja6WL4xt/jvg60lCik185lkpClP+gSp\nh0DzXaXeMpm29HBu8JqXFN2I460jRYHf6NwhCvTO/qHyLkLU11zVEFl+a298AahA\nNU1ms1U2aaYYYXBkPLtN1Uyr6BeEtgyOi926wySdMNQzPSLGmgdpkuuFWDCI94y6\n8t/a8hhKGKtWtLQuAvXxE91eTZlJyETalQ5xhpGAcv+e1UQAlF8V3ELlunqD2BpO\nh6N3ipct+HopRdp/cQ/2weNUeDc2sTv9JR6vnGiOa9VpZ017RRPMC6RaGDJLgtKo\nigXrMrsnn9kCAwEAAaAAMA0GCSqGSIb3DQEBCwUAA4IBAQBCb71iIsm+ak94qO2+\nn7+WYLkIPCyIDb5mBCqJi5AL1ZC+WqbNVf4NqC6zS9qJbeQGOId5sGVLkdJjcccg\nf6SrE0mrC1h43ttwkZGNWML+rO0OlEuEDYdfsUQuH24t9KQNf2c6pmdLdchNovFz\nblhmHdjcUUAVYHHrFPgT0uvQVYEFLLIGa2ZHVeTJvZf4IVW2SiezSt/d6NsHi3s1\nrVZ8UIXXaFsOkgF65+D14hW+t9GzajSYY/IlU4E5YCRO9lHM/YmlbQRNXJgHDMta\n/uh2hhK3mMR7sfeBhHYvqs1hxBaLEka5rKOO61q8Px9eCC+WZx2nyHFILp86RyT0\nmL9R\n-----END CERTIFICATE REQUEST-----\n"
        }'

Response

The information about this identity certificate

Status Code

  • The identity certificate was created successfully.

  • An invalid identity certificate prototype object was provided.

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

Example responses
  • {
      "certificates": [
        "-----BEGIN CERTIFICATE-----\nMIIDmTCCAoECFDGlhn2VlwNEQymsNpyt9rOiiiWDMA0GCSqGSIb3DQEBCwUAMIGJ\nMQswCQYDVQQGEwJVUzESMBAGA1UECAwJTWlubmVzb3RhMRIwEAYDVQQHDAlSb2No\nZXN0ZXIxDDAKBgNVBAoMA0lCTTEeMBwGA1UECwwVVmlydHVhbCBQcml2YXRlIENs\nb3VkMSQwIgYDVQQDDBtWUEMgRXhhbXBsZSBJbnRlcm1lZGlhdGUgQ0EwHhcNMjIx\nMTAxMTM1MDE0WhcNMjIxMTAxMTQyMDE0WjCBhzELMAkGA1UEBhMCVVMxEjAQBgNV\nBAgMCU1pbm5lc290YTESMBAGA1UEBwwJUm9jaGVzdGVyMQwwCgYDVQQKDANJQk0x\nHjAcBgNVBAsMFVZpcnR1YWwgUHJpdmF0ZSBDbG91ZDEiMCAGA1UEAwwZRXhhbXBs\nZSBTaGFyZSBDZXJ0aWZpY2F0ZTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC\nggEBAM6JytY3R4zWo3zzw/dM9ldUw8TIDQ9dNt+0sm3bFHHlAXaSKvmI+Ls/uQoh\n9VPpRLTx+WyljnKNnkXC6BQOzlugjAfi8hE2f5CC0A0m58XcBiZqH5BwTeLI4vVZ\nO9pLySckkEtHcmFE4h70KS5+1jDApeOTTS6EJsQcal/AAVYg7PDyXr1jE2HTKxnt\nlXopB/+bvWmBQ2k50Km0h0D1n0Ipoqqwb1wwWCrzQ2ds2XNKCUGkCgN6buFiF2nN\nLYS1tsIaw6OsTx+VheNGlYdlOhMUVypCok9JQ85P4NU47O6YgITX1V63ewZBnn5p\napywqdg8K2X2YgU/tLdpl5Jz2ysCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEABuOX\npxGbBQPdG3VGkNCYScZUcxocqmx4mCegBFfv4PjWU2+eG+3JikB3YWwqD11hixQm\n5Qwge/zMXzuKPs5D4yyblpDJlq5Iz/0VMjEl2paCHg9nm5Z3QaSydFH3SCGwfvld\nRn9ib6DSw4a58hmqON+CiWUSSibQy46gUsqVvYhq2lJimejTAN2DlePY2su1xvNV\nAdmDjmvO7j7YV/eWk6r7OgcqtVaAovN3okaybwxf8sLAFxLzp/aUaqXL10qJ/ISz\nVL+UHN7t5WzjHdh2OjDXwz0BOyhdbjyNX8ptKd+E0O21PsFFe8ErfShDh00g/ERP\nzXuEUsCxzTyWRTm8GA==\n-----END CERTIFICATE-----\n",
        "-----BEGIN CERTIFICATE-----\nMIIEADCCAuigAwIBAgIUDzQruKqvBY7+CS6DL0u93Na6cLMwDQYJKoZIhvcNAQEL\nBQAwgYExCzAJBgNVBAYTAlVTMRIwEAYDVQQIDAlNaW5uZXNvdGExEjAQBgNVBAcM\nCVJvY2hlc3RlcjEMMAoGA1UECgwDSUJNMR4wHAYDVQQLDBVWaXJ0dWFsIFByaXZh\ndGUgQ2xvdWQxHDAaBgNVBAMME1ZQQyBFeGFtcGxlIFJvb3QgQ0EwHhcNMjIxMTAx\nMDM0OTI5WhcNMjcxMDMxMDM0OTI5WjCBiTELMAkGA1UEBhMCVVMxEjAQBgNVBAgM\nCU1pbm5lc290YTESMBAGA1UEBwwJUm9jaGVzdGVyMQwwCgYDVQQKDANJQk0xHjAc\nBgNVBAsMFVZpcnR1YWwgUHJpdmF0ZSBDbG91ZDEkMCIGA1UEAwwbVlBDIEV4YW1w\nbGUgSW50ZXJtZWRpYXRlIENBMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC\nAQEAxjvxOtSFKsJKl4teBLgkX4+myxhClz2Qmg5MnNQ+oyhyNrpYvjG3+O+DrSUK\nKTXzmWSkKU/6BKmHQPNdpd4ymbb0cG7wmpcU3YjjrSNFgd/o3CEK9M7+ofIuQtTX\nXNUQWX5rb3wBqEA1TWazVTZpphhhcGQ8u03VTKvoF4S2DI6L3brDJJ0w1DM9Isaa\nB2mS64VYMIj3jLry39ryGEoYq1a0tC4C9fET3V5NmUnIRNqVDnGGkYBy/57VRACU\nXxXcQuW6eoPYGk6Ho3eKly34eilF2n9xD/bB41R4NzaxO/0lHq+caI5r1WlnTXtF\nE8wLpFoYMkuC0qiKBesyuyef2QIDAQABo2YwZDAdBgNVHQ4EFgQU2MIYc9g4Z7Kj\n79u2HPGYyTk5QHwwHwYDVR0jBBgwFoAUVnTLKJHyjHUcRp22jx+d3uGqnrwwEgYD\nVR0TAQH/BAgwBgEB/wIBADAOBgNVHQ8BAf8EBAMCAYYwDQYJKoZIhvcNAQELBQAD\nggEBADhOBfnBEaWVWCsZo3UR7UlP5/8i3mRgyFt4YkICPMacy2IcnDw8aoyjTO5b\n4BLO4J1m4AmcJnDJcFIEKLBSNbzsiDdP2rWIAAJKO4gKxdTArIuLgq7zrR74j46L\nn6IFwumKQRw0diGYD6wWIo/f9kGy1NQ46igmRYrEfzA5HWitEpF0mu6lz8mZ8m9s\na6CTEqwLFhP+qOcWtpGjNTa+OHENAmmAR4mR4Os4MsBBnb4RA//S/4suW419Cz8N\n1/Ul7KduYRKpRMSiS9YWbCvC5WiEvOvfp8Z4ecXlC+ohU5MLuCRPfP+blBvxNx2O\nsLotlbzDpim/gYiJCHgW3POlsLE=\n-----END CERTIFICATE-----\n"
      ],
      "created_at": "2022-11-01T13:50:14Z",
      "expires_at": "2022-11-01T14:20:14Z",
      "expires_in": 1800,
      "id": "9fd84246-7df4-4667-94e4-8ecde51d5ac5"
    }
  • {
      "errors": [
        {
          "code": "invalid_value",
          "message": "The value provided for the `expires_in` field must be between `300` and\n`3600`.",
          "more_info": "https://cloud.ibm.com/apidocs/vpc-identity#create-certificate-request",
          "target": {
            "name": "expires_in",
            "type": "field",
            "value": "7200"
          }
        }
      ],
      "status_code": 400,
      "trace": "e37872f6-f9a4-4084-a1a8-e56a1c8c8d3d"
    }
id=curlclassName=tab-item-selected