IBM Cloud API Docs

Introduction

This reference includes the full IBM Cloud® Virtual Private Cloud (VPC) Identity API, as well as newly released open beta features. This reference may also include limited beta features for customer accounts with special approval to preview those features.

The Beta IBM Cloud® Virtual Private Cloud (VPC) Identity API provides methods through the metadata service to generate an IAM access token from an identity access token to gain access to virtual server instances or bare metal servers. Access tokens eliminate the risk of accidental exposure of API keys, passwords, and long-lived access tokens used by automation on bare metal servers.

Access to API services is available from within the instance itself and is inaccessible from outside the virtual server instance or bare metal server. Metadata provided by API services pertains only to the instance from which the request is made. It is not possible to use metadata API services within an instance to obtain information about another instance or to obtain information about resources not currently associated with the instance.

Optionally, 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

By default, instances and bare metal servers are created with the metadata service endpoint disabled. You can enable the metadata service when creating or updating an instance or when creating or updating a bare metal server.

The Metadata API 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 access token. You can later generate an IAM access token by using an instance identity token and then use that token to access IAM-enabled services. For more information, see Configure the instance 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 or use any parser of your choice.

Consider storing the metadata endpoint in a variable. Use the example on this page. 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-07-29&generation=2&maturity=beta"   -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-07-29:08:39.363Z",
  "expires_at": "2025-07-29: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-07-29&generation=2&maturity=beta"   -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 beta API behavior for any date value in the version parameter between 2025-07-15 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.

API requests must specify a version query parameter date value within the last 45 days.

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, beta API requests must specify a maturity=beta query parameter. Omitting beta results in the GA version of the API being used, which can result in different behavior.

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-07-29&maturity=beta"   -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 beta 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-07-22 and 2025-07-29.

    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 API maturity. For the API behavior documented here, specify beta.

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

The IAM access token prototype.

  • curl -X POST "$vpc_metadata_api_endpoint/identity/v1/iam_tokens?version=2025-07-29&maturity=beta" -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-07-22 and 2025-07-29.

    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 API maturity. For the API behavior documented here, specify beta.

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

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-07-29&maturity=beta" -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-07-22 and 2025-07-29.

    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 API maturity. For the API behavior documented here, specify beta.

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

The identity certificate prototype

  • curl -X POST "$vpc_metadata_api_endpoint/identity/v1/certificates?version=2025-07-29&maturity=beta" -H "Authorization: Bearer $identity_token" -d '{
          "csr": |
            -----BEGIN CERTIFICATE REQUEST-----
            MIICzzCCAbcCAQAwgYkxCzAJBgNVBAYTAlVTMRIwEAYDVQQIDAlNaW5uZXNvdGEx
            EjAQBgNVBAcMCVJvY2hlc3RlcjEMMAoGA1UECgwDSUJNMR4wHAYDVQQLDBVWaXJ0
            dWFsIFByaXZhdGUgQ2xvdWQxJDAiBgNVBAMMG1ZQQyBFeGFtcGxlIEludGVybWVk
            aWF0ZSBDQTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMY78TrUhSrC
            SpeLXgS4JF+PpssYQpc9kJoOTJzUPqMocja6WL4xt/jvg60lCik185lkpClP+gSp
            h0DzXaXeMpm29HBu8JqXFN2I460jRYHf6NwhCvTO/qHyLkLU11zVEFl+a298AahA
            NU1ms1U2aaYYYXBkPLtN1Uyr6BeEtgyOi926wySdMNQzPSLGmgdpkuuFWDCI94y6
            8t/a8hhKGKtWtLQuAvXxE91eTZlJyETalQ5xhpGAcv+e1UQAlF8V3ELlunqD2BpO
            h6N3ipct+HopRdp/cQ/2weNUeDc2sTv9JR6vnGiOa9VpZ017RRPMC6RaGDJLgtKo
            igXrMrsnn9kCAwEAAaAAMA0GCSqGSIb3DQEBCwUAA4IBAQBCb71iIsm+ak94qO2+
            n7+WYLkIPCyIDb5mBCqJi5AL1ZC+WqbNVf4NqC6zS9qJbeQGOId5sGVLkdJjcccg
            f6SrE0mrC1h43ttwkZGNWML+rO0OlEuEDYdfsUQuH24t9KQNf2c6pmdLdchNovFz
            blhmHdjcUUAVYHHrFPgT0uvQVYEFLLIGa2ZHVeTJvZf4IVW2SiezSt/d6NsHi3s1
            rVZ8UIXXaFsOkgF65+D14hW+t9GzajSYY/IlU4E5YCRO9lHM/YmlbQRNXJgHDMta
            /uh2hhK3mMR7sfeBhHYvqs1hxBaLEka5rKOO61q8Px9eCC+WZx2nyHFILp86RyT0
            mL9R
            -----END CERTIFICATE REQUEST-----
        }'

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