Power Virtual Servers Metadata Service

Introduction The Power Virtual Server Metadata and Identity APIs provide methods through the Power Virtual Server Metadata service to retrieve instance metadata and manage identity tokens. These APIs allow virtual server instances to retrieve information about themselves and obtain access tokens for IAM-enabled IBM Cloud services. The API provides two main capabilities: - Instance metadata: Retrieve information about the calling virtual server instance, including configuration details, network settings, and system properties. - Identity and access tokens: Create identity tokens and exchange them for IAM access tokens to securely access other IBM Cloud services. You can access the metadata and instance API endpoints only from within the Power Virtual Server environment. Metadata provided by the metadata API pertains only to the instance from which the request is made. If an IBM Cloud Identity and Access Management IAM trusted profilehttps://cloud.ibm.com/docs/iam?topic=iam-trusted-profile-iam-token&interface=ui is linked to the virtual server instance, the IAM token can be used to access IAM-enabled IBM Cloud services, such as API Connecthttps://cloud.ibm.com/catalog/services/api-connect, Event Streamshttps://cloud.ibm.com/apidocs/event-streams/restproducer, Secrets Managerhttps://cloud.ibm.com/apidocs/secrets-manager, and Cloud Object Storagehttps://cloud.ibm.com/docs/cloud-object-storage/api-reference. Endpoint URL By default, metadata service endpoints are disabled for a Power Virtual Server instance. You can enable access to the metadata service endpoints when you create or update an instance. You can access the metadata service from within the virtual server instance by using the endpoint URL https://api.metadata.power-iaas.cloud.ibm.com. When the metadataService.enabled property is set to false, the metadata API is not available, and the endpoint URL does not respond to requests. This example stores the Power Virtual Server metadata service endpoint in a pvsapiendpoint variable. sh pvsapiendpoint=https://api.metadata.power-iaas.cloud.ibm.com Authentication To start an authenticated session, you must create an identity token by calling the PUT /identity/v1/tokencreate-identity-token method from within a Power Virtual Server instance. Then, pass that token in the Authorization header when you call other API methods. To access IAM-enabled services, exchange the identity token for an IAM token by calling the POST /identity/v1/iamtokenscreate-identity-iam-token method with a trusted profile linked to the instance. A session lasts for the lifetime of the token. You can reuse a token for multiple API requests until it expires. The virtual machine instance calls the metadata service endpoints directly and does not use granular IAM action mappings. As a result, metadata service actions do not appear in the custom role creation page. Access is controlled through trusted profile configurations, such as trust relationships and resource links. These examples use jq as a parser, a third-party tool licensed under the MIT licensehttps://stedolan.github.io/jq/download/. You might need to install jq, or you can use any parser of your choice. This example extracts the access token value and stores it in the identitytoken environment variable. sh identitytoken=curl -X PUT \ "$pvsapiendpoint/identity/v1/token" \ -H 'content-type: application/json' \ -H "Metadata-Flavor: ibm" \ -H "Accept: application/json" \ -d '{ \ "expiresin": 300 \ }' | jq -r '.accesstoken' Example response from the previous request: text { "accesstoken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3NjUzOTA0NzMsImlhdCI6MTc2NTM4Njg3M30.signature", "createdat": "2026-04-10T06:00:00Z", "expiresat": "2026-04-10T06:05:00Z", "expiresin": 300 } This example uses the identitytoken environment variable from the previous example to create an IAM token for a trusted profile that is linked to the instance. sh iamtoken=curl -X POST \ "$pvsapiendpoint/identity/v1/iamtokens?" \ -H "Authorization: Bearer $identitytoken" \ -H "Metadata-Flavor: ibm" \ -H "Accept: application/json" \ -d '{ "trustedprofile": { "id": "Profile-8dd84246-7df4-4667-94e4-8cede51d5ac5" } }' | jq -r '.accesstoken' This example uses the identitytoken to retrieve metadata about the calling instance. sh curl -X GET \ "$pvsapiendpoint/metadata/v1/instance" \ -H "Authorization: Bearer $identitytoken" \ -H "Metadata-Flavor: ibm" \ -H "Accept: application/json" Auditing You can monitor API activity for Power Virtual Server by using IBM Cloud Activity Tracker Event Routing, a platform service, to route auditing events to a destination of your choice. Activity tracking events report on activities that change the state of resources in IBM Cloud. They also report on certain activities that do not change any state, such as attempts to access and update resources. You can configure targets and routes to control where IBM Cloud Activity Tracker Event Routing sends activity tracking events. Each time you make an API call, one or more events are generated that you can track and audit. 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. Error handling This API uses standard HTTP response codes to indicate the outcome of a request. A 2xx response indicates success. A 4xx response indicates a failure that you must resolve. A 5xx response indicates a service failure. | HTTP error code | Description | Resolution | | --------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------- | | 200 | Success | The request was successful. | | 201 | Created | The request was successful and a resource was created. | | 400 | Bad Request | The input parameters in the request are incomplete or not in the expected format. | | 401 | Unauthorized | The authentication token is missing, invalid, or expired. | | 403 | Forbidden | The supplied authentication is not authorized to perform the requested operation. | | 404 | Not Found | The requested resource could not be found or is not associated with the calling instance. | | 408 | Request Timeout | The connection to the server timed out. Wait a few minutes and try again. | | 429 | Too Many Requests | Too many requests were sent in a given amount of time. Wait before retrying the request. | | 500 | Internal Server Error | An unexpected condition prevented the service from fulfilling the request. | | 501 | Not Implemented | The server does not recognize the request method or lacks the ability to fulfill the request. | | 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 due to temporary overloading or maintenance. | | 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. | API best practices Follow these best practices to reduce the risk of compatibility issues 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 documented for the API. - Use a fixed API version that is compatible with your application. - Avoid depending on undocumented behavior. Related APIs - Power Virtual Server APIhttps://cloud.ibm.com/apidocs/power-cloud