Instana User API
The User API from Instana — 7 operation(s) for user.
OpenAPI Specification
openapi: 3.0.1
info:
contact:
email: support@instana.com
name: © Instana
url: http://instana.com
termsOfService: https://www.instana.com/terms-of-use/
title: Instana REST API documentation User API
version: 1.307.1417
x-ibm-ahub-try: true
x-logo:
altText: instana logo
backgroundColor: '#FAFBFC'
url: header-logo.svg
description: "Searching for answers and best pratices? Check our [IBM Instana Community](https://community.ibm.com/community/user/aiops/communities/community-home?CommunityKey=58f324a3-3104-41be-9510-5b7c413cc48f).\n\n<div style=\"background-color:#e6f0ff; padding: 12px; border-left: 6px solid #0052cc; font-size: 14px; display: flex; align-items: center;\">\n <img src=\"https://img.icons8.com/ios-filled/50/0052cc/info.png\" width=\"18\" height=\"18\" style=\"margin-right: 8px;\" alt=\"info icon\"/>\n <span>\n <b>Our API documentation is moving to</b> \n <a href=\"https://developer.ibm.com/apis/catalog/instana--instana-rest-api/Introduction\" target=\"_blank\">API Hub</a>\n\t — please update your bookmarks now, as the current site will be deprecated after Release-306.\n </span>\n</div>\n\n## Overview\nThe Instana REST API provides programmatic access to the Instana platform. It can be used to retrieve data available through the Instana UI Dashboard -- metrics, events, traces, etc -- and also to automate configuration tasks such as user management.\n\n### Navigating the API documentation\nThe API endpoints are grouped by product area and functionality. This generally maps to how our UI Dashboard is organized, hopefully making it easier to locate which endpoints you'd use to fetch the data you see visualized in our UI. The [UI sections](https://www.ibm.com/docs/en/instana-observability/current?topic=working-user-interface#navigation-menu) include:\n- Websites & Mobile Apps\n- Applications\n- Infrastructure\n- Synthetic Monitoring\n- Events\n- Automation\n- Service Levels\n- Settings\n- etc\n\n### Rate Limiting\nA rate limit is applied to API usage. Up to 5,000 calls per hour can be made. How many remaining calls can be made and when this call limit resets, can inspected via three headers that are part of the responses of the API server.\n\n- **X-RateLimit-Limit:** Shows the maximum number of calls that may be executed per hour.\n- **X-RateLimit-Remaining:** How many calls may still be executed within the current hour.\n- **X-RateLimit-Reset:** Time when the remaining calls will be reset to the limit. For compatibility reasons with other rate limited APIs, this date is not the date in milliseconds, but instead in seconds since 1970-01-01T00:00:00+00:00.\n\n### Further Reading\nWe provide additional documentation for our REST API in our [product documentation](https://www.ibm.com/docs/en/instana-observability/current?topic=apis-web-rest-api). Here you'll also find some common queries for retrieving data and configuring Instana.\n\n## Getting Started with the REST API\n\n### API base URL\nThe base URL for an specific instance of Instana can be determined using the tenant and unit information.\n- `base`: This is the base URL of a tenant unit, e.g. `https://test-example.instana.io`. This is the same URL that is used to access the Instana user interface.\n- `apiToken`: Requests against the Instana API require valid API tokens. An initial API token can be generated via the Instana user interface. Any additional API tokens can be generated via the API itself.\n\n### Curl Example\nHere is an Example to use the REST API with Curl. First lets get all the available metrics with possible aggregations with a GET call.\n\n```bash\ncurl --request GET \\\n --url https://test-instana.instana.io/api/application-monitoring/catalog/metrics \\\n --header 'authorization: apiToken xxxxxxxxxxxxxxxx'\n```\n\nNext we can get every call grouped by the endpoint name that has an error count greater then zero. As a metric we could get the mean error rate for example.\n\n```bash\ncurl --request POST \\\n --url https://test-instana.instana.io/api/application-monitoring/analyze/call-groups \\\n --header 'authorization: apiToken xxxxxxxxxxxxxxxx' \\\n --header 'content-type: application/json' \\\n --data '{\n \"group\":{\n \"groupbyTag\":\"endpoint.name\"\n },\n \"tagFilters\":[\n \t{\n \t\t\"name\":\"call.error.count\",\n \t\t\"value\":\"0\",\n \t\t\"operator\":\"GREATER_THAN\"\n \t}\n ],\n \"metrics\":[\n \t{\n \t\t\"metric\":\"errors\",\n \t\t\"aggregation\":\"MEAN\"\n \t}\n ]\n }'\n```\n\n### Generating REST API clients\n\nThe API is specified using the [OpenAPI v3](https://github.com/OAI/OpenAPI-Specification) (previously known as Swagger) format.\nYou can download the current specification at our [GitHub API documentation](https://instana.github.io/openapi/openapi.yaml).\n\nOpenAPI tries to solve the issue of ever-evolving APIs and clients lagging behind. Please make sure that you always use the latest version of the generator, as a number of improvements are regularly made.\nTo generate a client library for your language, you can use the [OpenAPI client generators](https://github.com/OpenAPITools/openapi-generator).\n\n#### Go\nFor example, to generate a client library for Go to interact with our backend, you can use the following script; mind replacing the values of the `UNIT_NAME` and `TENANT_NAME` environment variables using those for your tenant unit:\n\n```bash\n#!/bin/bash\n\n### This script assumes you have the `java` and `wget` commands on the path\n\nexport UNIT_NAME='myunit' # for example: prod\nexport TENANT_NAME='mytenant' # for example: awesomecompany\n\n//Download the generator to your current working directory:\nwget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/4.3.1/openapi-generator-cli-4.3.1.jar -O openapi-generator-cli.jar --server-variables \"tenant=${TENANT_NAME},unit=${UNIT_NAME}\"\n\n//generate a client library that you can vendor into your repository\njava -jar openapi-generator-cli.jar generate -i https://instana.github.io/openapi/openapi.yaml -g go \\\n -o pkg/instana/openapi \\\n --skip-validate-spec\n\n//(optional) format the Go code according to the Go code standard\ngofmt -s -w pkg/instana/openapi\n```\n\nThe generated clients contain comprehensive READMEs, and you can start right away using the client from the example above:\n\n```go\nimport instana \"./pkg/instana/openapi\"\n\n// readTags will read all available application monitoring tags along with their type and category\nfunc readTags() {\n\tconfiguration := instana.NewConfiguration()\n\tconfiguration.Host = \"tenant-unit.instana.io\"\n\tconfiguration.BasePath = \"https://tenant-unit.instana.io\"\n\n\tclient := instana.NewAPIClient(configuration)\n\tauth := context.WithValue(context.Background(), instana.ContextAPIKey, instana.APIKey{\n\t\tKey: apiKey,\n\t\tPrefix: \"apiToken\",\n\t})\n\n\ttags, _, err := client.ApplicationCatalogApi.GetApplicationTagCatalog(auth)\n\tif err != nil {\n\t\tfmt.Fatalf(\"Error calling the API, aborting.\")\n\t}\n\n\tfor _, tag := range tags {\n\t\tfmt.Printf(\"%s (%s): %s\\n\", tag.Category, tag.Type, tag.Name)\n\t}\n}\n```\n\n#### Java\nFollow the instructions provided in the official documentation from [OpenAPI Tools](https://github.com/OpenAPITools) to download the [openapi-generator-cli.jar](https://github.com/OpenAPITools/openapi-generator?tab=readme-ov-file#13---download-jar).\n\nDepending on your environment, use one of the following java http client implementations which will create a valid client for our OpenAPI specification:\n```\n//Nativ Java HTTP Client\njava -jar openapi-generator-cli.jar generate -i https://instana.github.io/openapi/openapi.yaml -g java -o pkg/instana/openapi --skip-validate-spec -p dateLibrary=java8 --library native\n\n//Spring WebClient\njava -jar openapi-generator-cli.jar generate -i https://instana.github.io/openapi/openapi.yaml -g java -o pkg/instana/openapi --skip-validate-spec -p dateLibrary=java8,hideGenerationTimestamp=true --library webclient\n\n//Spring RestTemplate\njava -jar openapi-generator-cli.jar generate -i https://instana.github.io/openapi/openapi.yaml -g java -o pkg/instana/openapi --skip-validate-spec -p dateLibrary=java8,hideGenerationTimestamp=true --library resttemplate\n\n```\n"
servers:
- description: Instana Backend
url: https://{unit}-{tenant}.instana.io
variables:
tenant:
default: tenant
description: Customer tenant unit
unit:
default: unit
description: Customer tenant name
- description: Instana Self-Hosted Backend
url: https://{domain}
variables:
domain:
default: example.com
description: Customer Self-Hosted domain
tags:
- name: User
paths:
/api/settings/invitation/share:
post:
operationId: shareAndInviteUsers
requestBody:
content:
application/json:
example:
- email: username@example.com
groupId: '-1'
message: hello message
path: /testpath
schema:
type: array
items:
$ref: '#/components/schemas/Invitation'
required: true
responses:
'200':
content:
application/json:
example:
invitationResults:
- userEmail: username@example.com
invitationStatus: SUCCESS
schema:
type: array
items:
$ref: '#/components/schemas/InvitationResponse'
description: OK
'400':
content:
application/json:
example:
errors:
- Please set at least one email
schema:
type: string
description: Bad Request Error
security:
- ApiKeyAuth:
- CanConfigureUsers
summary: Send user invitations
tags:
- User
x-ibm-ahub-byok: true
description: "This API endpoint allows to invite users to this tenant. \nEach user requires the email address and the group to which the user will be added initially. \n\nInviting users whilst an IdP is configured will always result in failures, as in this case users will be provisioned during the login based on the IdP configuration. \nDuring the IdP configurations all pending invitations are automatically revoked.\n\nInviting users who are already members of the tenant will also provide an error result. "
/api/settings/invitations:
delete:
operationId: revokePendingInvitation
parameters:
- description: Email of the invite for removal
example: username@example.com
in: query
name: email
required: true
schema:
type: string
responses:
default:
content:
application/json: {}
description: default response
security:
- ApiKeyAuth:
- CanConfigureUsers
summary: Revoke pending invitation
tags:
- User
x-ibm-ahub-byok: true
description: 'This API endpoint allows to delete an invitation, requires the users’ email as a Query parameter.
'
get:
operationId: getInvitations
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/InvitationResult'
description: OK
security:
- ApiKeyAuth:
- CanConfigureUsers
summary: All pending invitations
tags:
- User
x-ibm-ahub-byok: true
description: "This API endpoint retrieves the list of all pending invitations. \nDuring the IdP configuration all pending invitations will be dismissed and whilst an IdP is configured invitations are prevented. "
post:
operationId: inviteUsers
requestBody:
content:
application/json:
example:
- email: username@example.com
groupId: '-1'
schema:
type: array
items:
$ref: '#/components/schemas/Invitation'
required: true
responses:
'200':
content:
application/json:
example:
invitationResults:
- userEmail: username@example.com
invitationStatus: SUCCESS
schema:
type: array
items:
$ref: '#/components/schemas/InvitationResponse'
description: OK
'400':
content:
application/json:
example:
errors:
- Please set at least one email
schema:
type: string
description: Bad Request Error
security:
- ApiKeyAuth:
- CanConfigureUsers
summary: Send user invitations
tags:
- User
x-ibm-ahub-byok: true
description: "This API endpoint allows to invite users to this tenant. \nEach user requires the email address and the group to which the user will be added initially. \n\nInviting users whilst an IdP is configured will always result in failures, as in this case users will be provisioned during the login based on the IdP configuration. \nDuring the IdP configurations all pending invitations are automatically revoked.\n\nInviting users who are already members of the tenant will also provide an error result. "
/api/settings/users:
get:
description: Retrieves all users with access to the tenant. The result will not contain pending invitations.
operationId: getUsers
responses:
'200':
content:
application/json:
example:
- id: userId
email: username@example.com
fullName: username
lastLoggedIn: 1636434847190
groupCount: 1
tfaEnabled: false
schema:
type: array
items:
$ref: '#/components/schemas/UserResult'
description: OK
'401':
description: Unauthorized access - requires user authentication.
'403':
description: Insufficient permissions.
security:
- ApiKeyAuth:
- CanConfigureUsers
summary: All users (without invitations)
tags:
- User
x-ibm-ahub-byok: true
/api/settings/users/delete:
put:
description: Remove multiple users access to the tenant. Removing a user from a tenant does not delete their user account.
operationId: removeUsersFromTenant
requestBody:
content:
'*/*':
schema:
type: array
items:
type: string
uniqueItems: true
required: true
responses:
'204':
description: Successful - no content to return.
'401':
description: Unauthorized access - requires user authentication.
'403':
description: Insufficient permissions.
security:
- ApiKeyAuth:
- CanConfigureUsers
summary: Remove users from tenant
tags:
- User
x-ibm-ahub-byok: true
/api/settings/users/overview:
get:
description: Retrieves all users with access to the tenant. The result will also contain pending invitations.
operationId: getUsersIncludingInvitations
responses:
'200':
content:
application/json:
example:
users:
- id: userId1
email: username@example.com
fullName: fullName
lastLoggedIn: 1699313025975
groupCount: null
tfaEnabled: null
invitations:
- id: userId2
email: username2@example.com
groupId: '-3'
schema:
$ref: '#/components/schemas/UsersResult'
description: OK
'401':
description: Unauthorized access - requires user authentication.
'403':
description: Insufficient permissions.
security:
- ApiKeyAuth:
- CanConfigureUsers
summary: All users (incl. invitations)
tags:
- User
x-ibm-ahub-byok: true
/api/settings/users/{email}:
put:
description: Updates the full name of the user.
operationId: updateUser
parameters:
- in: path
name: email
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
fullName: Updated Name
schema:
$ref: '#/components/schemas/EditUser'
responses:
'204':
description: Successful - no content to return.
'401':
description: Unauthorized access - requires user authentication.
'403':
description: Insufficient permissions.
'404':
description: Resource not found.
security:
- ApiKeyAuth:
- CanConfigureUsers
summary: Change user name of single user
tags:
- User
x-ibm-ahub-byok: true
/api/settings/users/{userId}:
delete:
description: Remove the users access to the tenant. Removing a user from a tenant does not delete their user account.
operationId: removeUserFromTenant
parameters:
- description: Id of the user for removal
example: userId
in: path
name: userId
required: true
schema:
type: string
responses:
'204':
description: Successful - no content to return.
'401':
description: Unauthorized access - requires user authentication.
'403':
description: Insufficient permissions.
security:
- ApiKeyAuth:
- CanConfigureUsers
summary: Remove user from tenant
tags:
- User
x-ibm-ahub-byok: true
get:
description: Retrieves the user with access to the tenant.
operationId: getUserById
parameters:
- description: Id of the user for retrieval
example: userId
in: path
name: userId
required: true
schema:
type: string
style: simple
responses:
'200':
content:
application/json:
example:
id: userId
preferredName: preferredName
fullName: fullName
email: username@example.com
encryptedPassword: ''
lastLoggedIn: 1699442707385
timestampAcceptedTos: 1696404223545
timestampAcceptedPrivacyAgreement: 1696404223545
acceptedTosVersion: 6
acceptedPrivacyAgreementVersion: 9
tenantsWhereMainContact: []
tenants: []
createDate: 1696404196256
emailConfirmed: true
tenantIds:
- 55557f97186b9c0007857730
passwordResetAttempt: 0
groupCount: null
tfaEnabled: null
role: null
schema:
type: array
items:
$ref: '#/components/schemas/UserResult'
description: OK
'401':
description: Unauthorized access - requires user authentication.
'403':
description: Insufficient permissions.
security:
- ApiKeyAuth:
- CanConfigureUsers
summary: Get single user
tags:
- User
x-ibm-ahub-byok: true
components:
schemas:
InvitationResponse:
type: object
properties:
invitationResults:
type: array
items:
$ref: '#/components/schemas/InvitationResult'
EditUser:
type: object
properties:
fullName:
type: string
required:
- fullName
InvitationResult:
type: object
properties:
invitationStatus:
type: string
enum:
- SUCCESS
- INTERNAL_ERROR
- FAILURE_USER_ALREADY_EXISTS
- FAILURE_USER_ALREADY_INVITED
- FAILURE_ONLY_DEFAULT_GROUP_INVITATION_ALLOWED
- FAILURE_TENANT_IDP_CONFIGURED
userEmail:
type: string
UsersResult:
type: object
properties:
invitations:
type: array
items:
$ref: '#/components/schemas/InvitationResult'
uniqueItems: true
users:
type: array
items:
$ref: '#/components/schemas/UserResult'
uniqueItems: true
UserResult:
type: object
properties:
email:
type: string
fullName:
type: string
groupCount:
type: integer
format: int64
id:
type: string
lastLoggedIn:
type: integer
format: int64
tfaEnabled:
type: boolean
required:
- email
- fullName
- id
Invitation:
type: object
properties:
email:
type: string
groupId:
type: string
message:
type: string
path:
type: string
required:
- email
- groupId
securitySchemes:
ApiKeyAuth:
in: header
name: authorization
type: apiKey
description: "## Example\n\n```bash\ncurl --request GET \\\n --url https://test-instana.instana.io/api/application-monitoring/catalog/metrics \\\n --header 'authorization: apiToken xxxxxxxxxxxxxxxx'\n```\n"
x-tagGroups:
- name: Websites & Mobile Apps
tags:
- Website Metrics
- Website Catalog
- Website Analyze
- Website Configuration
- Mobile App Metrics
- Mobile App Catalog
- Mobile App Analyze
- Mobile App Configuration
- End User Monitoring
- name: Applications
tags:
- Application Metrics
- Application Resources
- Application Catalog
- Application Analyze
- Application Settings
- Application Topology
- Application Alert Configuration
- Global Application Alert Configuration
- name: Infrastructure
tags:
- Infrastructure Analyze
- Infrastructure Metrics
- Infrastructure Resources
- Infrastructure Catalog
- Infrastructure Topology
- name: Logging
tags:
- Logging Analyze
- name: Synthetic Monitoring
tags:
- Synthetic Catalog
- Synthetic Metrics
- Synthetic Settings
- Synthetic Test Playback Results
- Synthetic Alert Configuration
- name: Logs
tags:
- Log Alert Configuration
- name: Events
tags:
- Events
- Event Settings
- name: Automation
tags:
- Action Catalog
- Action History
- Policies
- name: Service Levels
tags:
- SLI Settings
- SLI Report
- Apdex Settings
- Apdex Report
- Service Levels Objective(SLO) Configurations
- Service Levels Objective(SLO) Report
- Service Levels Alert Configuration
- SLO Correction Configurations
- SLO Correction Windows
- name: AI Management
tags:
- AI Management
- name: Settings
tags:
- Custom Dashboards
- User
- Groups
- Teams
- Roles
- Audit Log
- API Token
- Maintenance Configuration
- Synthetic Calls
- Session Settings
- Automation Settings
- Authentication
- name: Open Beta Features
tags:
- Infrastructure Analyze
- name: Closed Beta Features
tags:
- Infrastructure Alert Configuration
- name: Instana
tags:
- Releases
- Host Agent
- Health
- Usage