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. Contact your IBM sales representative if you are interested in getting access.
There are no backward-compatibility guarantees as a feature progresses through its beta phase, or from the final beta release to its initial GA release. Using features that are not GA mature could introduce the risk of corrupting resources in your account.
Read the introduction in the generally available Virtual Private Cloud Identity API for details on endpoint URLs, authentication, auditing, error handling, versioning, and other important information.
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
Request
Query Parameters
The API version, in format
YYYY-MM-DD. For the API behavior documented here, specify any date between2025-08-19and2025-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-23The 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.
Identifies a trusted profile by a unique property.
curl -X POST "$vpc_metadata_api_endpoint/identity/v1/iam_tokens?version=2025-08-27&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
The access token
Possible values: 14 ≤ length ≤ 2000, Value must match regular expression
^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$Example:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50IjoiYWEyNDMyYjFmYTRkNGFjZTg5MWU5YjgwZmMxMDRlMzQiLCJzZWNyZXQiOiJRVzRnWlhoaGJYQnNaU0J6WldOeVpYUUsiLCJleHAiOjE3MjYwNzU1OTR9.UFDVzzGJ54Go9Z4jgyPSLG49zNx-AjHTQrJA6ee8KLIThe date and time that the access token was created
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$Example:
2021-03-22T21:50:14ZThe date and time that the access token will expire
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$Example:
2021-03-22T21:51:14ZThe number of seconds remaining until the access token expires
Possible values: 5 ≤ value ≤ 3600
Example:
60
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
{ "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
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 between2025-08-19and2025-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-23The 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.
The number of seconds remaining until the access token expires
Possible values: 5 ≤ value ≤ 3600
Default:
300Example:
60
curl -X PUT "$vpc_metadata_api_endpoint/identity/v1/token?version=2025-08-27&maturity=beta" -H "Metadata-Flavor: ibm" -d '{}'
Response
The information about this access token
The access token
Possible values: 14 ≤ length ≤ 2000, Value must match regular expression
^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$Example:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50IjoiYWEyNDMyYjFmYTRkNGFjZTg5MWU5YjgwZmMxMDRlMzQiLCJzZWNyZXQiOiJRVzRnWlhoaGJYQnNaU0J6WldOeVpYUUsiLCJleHAiOjE3MjYwNzU1OTR9.UFDVzzGJ54Go9Z4jgyPSLG49zNx-AjHTQrJA6ee8KLIThe date and time that the access token was created
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$Example:
2021-03-22T21:50:14ZThe date and time that the access token will expire
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$Example:
2021-03-22T21:51:14ZThe number of seconds remaining until the access token expires
Possible values: 5 ≤ value ≤ 3600
Example:
60
Status Code
The identity token was created successfully.
An invalid identity token prototype object was provided.
{ "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
Request
Query Parameters
The API version, in format
YYYY-MM-DD. For the API behavior documented here, specify any date between2025-08-19and2025-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-23The 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
A Public-Key Cryptography Standards (PKCS) #10 certification request provided in textual encoding described by RFC 7468.
Certificate signing requests (CSRs) must meet the following requirements:
- Version: v1 (value
0) - Subject public key algorithm: 2048-bit or 4096-bit RSA
- Signature algorithm: SHA-256 with RSA encryption
- Attributes: empty (constructed DER encoding value
a0 00) - Subject: At least one of the following naming attributes must be specified:
C: The ISO 3166-1 alpha-2 country name (section 6.3.1 of X.520)L: The locality name (section 6.3.4 of X.520)ST: The full state or province name (section 6.3.5 of X.520)O: The organization name (section 6.4.1 of X.520)OU: The organizational unit name (section 6.4.2 of X.520)- No other naming attributes may be specified
See Generating an identity certificate by using an identity access token, ITU X.520 10/2019, RFC 5280, and RFC 2985 for more information.
Possible values: length ≥ 75, Value must match regular expression
^-----BEGIN CERTIFICATE REQUEST-----(\n|\r|\r\n)([0-9a-zA-Z\+\/=]{64}(\n|\r|\r\n))*([0-9a-zA-Z\+\/=]{1,63}(\n|\r|\r\n))?-----END CERTIFICATE REQUEST-----(\n|\r|\r\n)*$Examples:-----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------ Version: v1 (value
The number of seconds remaining until the identity certificate expires
Possible values: 300 ≤ value ≤ 3600
Default:
3600Example:
1800
curl -X POST "$vpc_metadata_api_endpoint/identity/v1/certificates?version=2025-08-27&maturity=beta" -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
The public key certificates, consisting of the identity certificate, and all intermediate CA certificates in its chain of trust. Certificates are based upon the X.509 v3 certificate format and the standard certificate extensions defined in RFC 5280.
The certificates are issued by an IBM Cloud Virtual Private Cloud (VPC) certification authority (CA). VPC provides the public key infrastructure (PKI) establishing a chain of trust for use with VPC file share services.
All certificates are provided in textual encoding described by RFC 7468.
Possible values: 1 ≤ number of items ≤ 10, contains only unique items, Value must match regular expression
^-----BEGIN CERTIFICATE-----(\n|\r|\r\n)([0-9a-zA-Z\+\/=]{64}(\n|\r|\r\n))*([0-9a-zA-Z\+\/=]{1,63}(\n|\r|\r\n))?-----END CERTIFICATE-----(\n|\r|\r\n)+$The date and time that the identity certificate was created
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$Example:
2022-11-01T13:50:14ZThe date and time that the identity certificate will expire
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$Example:
2022-11-01T14:20:14ZThe number of seconds remaining until the identity certificate expires
Possible values: 300 ≤ value ≤ 3600
Example:
1800The unique identifier for this identity certificate
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$Example:
9fd84246-7df4-4667-94e4-8ecde51d5ac5
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
{ "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" }