swagger: '2.0' info: description: >- This API provides operations to manage your access to customer IoT data, namely 1. The operations return a Technical Token, which gives access to the tenant's IoT data 2. Provides list of allowed users to an application hosted by Developer/Operator tenant ## Limitations - The service may decide to throttle API requests temporarily returning a 429 status code. version: 3.3.0 x-visibility: 'external' title: Technical Token Manager API produces: - application/json consumes: - application/json schemes: - https basePath: /api/technicaltokenmanager/v3 tags: - name: Token Operations description: >- Operations to get technical tokens. - name: User Tenant Operations description: >- Operations to get provisioned user tenants. securityDefinitions: userTenants: type: "oauth2" authorizationUrl: "http://UAA_DOMAIN//oauth/token" tokenUrl: "http://UAA_DOMAIN/oauth/token" flow: "accessCode" scopes: km.usr: "Permission to fetch user tenant records those have access to the app" paths: /oauth/token: post: operationId: getToken tags: - Token Operations summary: Issues technical token to access customer IoT data. description: OAuth 2.0 Client Credentials Grant (see RFC 6749). Endpoint requires client authentication via Authorization header using "Basic" scheme (see RFC 7617). parameters: - in: header name: X-SPACE-AUTH-KEY type: string required: true description: The X-SPACE-AUTH-KEY header value is a combination of your application's secret credentials, the user name / ID and password / values. Combine the two values, separating them with a colon, and Base64 encode the combined values. These credentials should be available in Environment variables of CF-space where application is deployed.Credentials - MDSP_KEY_STORE_CLIENT_ID MDSP_KEY_STORE_CLIENT_SECRET. Example "Basic ZGlvcDEtaGVybW..." - name: body in: body description: "contains appname, appVersion, host and user for which token is required." required: true schema: $ref: '#/definitions/Identification' responses: '200': description: returns a valid Technical Token. schema: $ref: '#/definitions/AccessTokenResponse' 'default': description: Other error with any status code and response body format. /oauthTokens: post: operationId: getOauthTokens tags: - Token Operations summary: Issues multiple technical tokens to access customer IoT data. description: | Returns a technical user access token for each user tenant ID specified in the request body. A maximum of 5 access tokens can be requested in one call. The operation can be used by operator and developer tenants. Custom authentication is required, as described in detail at paramter X-SPACE-AUTH-KEY. Token for developer or host tenant can be obtained by using userTenant = hostTenant in the request payload. parameters: - in: header name: X-SPACE-AUTH-KEY type: string required: true description: | Is used as authentication for this operation instead of a MindSphere Bearer access token. The value of this header must be constructed according to basic authentication as Basic Base64("clientID:clientSecret") where Base64(.) must be replaced by the Base64 encoded string of its argument string, including the separator colon. clientID and clientSecret can be obtained from the environment variables of a MindSphere CloudFoundry application, where the relation from environment variable to client credentials is given by MDSP_KEY_STORE_CLIENT_ID --> clientID MDSP_KEY_STORE_CLIENT_SECRET --> clientSecret - name: body in: body required: true schema: $ref: '#/definitions/TokensPayload' responses: '200': description: OK schema: $ref: '#/definitions/TokensResponse' '400': description: Possible errors described by error code ->
1. Number of userTenantIds should not be more than <>(mdsp.core.keymanager.invalidRequestBody)
2. Provide only hostTenantId(mdsp.core.keymanager.invalidRequestBody)
3. SetOfUserTenant field should not be empty(mdsp.core.keymanager.invalidRequestBody)
4. HostTenantId should not be empty(mdsp.core.keymanager.invalidRequestBody)
5. Invalid tenant in setOfUserTenant(mdsp.core.keymanager.invalidRequestBody) schema: $ref: '#/definitions/Errors' 'default': description: Other error with any status code and response body format. /userTenants: get: operationId: getUserTenantsByHost tags: - User Tenant Operations security: - userTenants: - "km.usr" summary: Provides list of user tenants provisioned to an application. description: | Provides a list of user tenant IDs for user tenants being provisioned to an application. Up to 500 tenant IDs are returned. The operation can be used by operator and developer tenants. Token for developer or host tenant can be obtained by calling "/oauth/token" or "/oauthTokens", using userTenant = hostTenant in the request payload. Token obtained in the previous step, is accepted for this endpoint. parameters: - $ref: '#/parameters/page' - $ref: '#/parameters/size' responses: '200': description: OK schema: $ref: '#/definitions/UserTenantResponse' '400': description: Possible errors described by error code ->
1. Invalid Host Token(mdsp.core.keymanager.invalidHostTokenFormat)
2. Unidentified User(mdsp.core.keymanager.unidentifiedUser)
3. Page Size specified is more than maximum supported page size(mdsp.core.keymanager.pageSizeForUserTenantsExceeded). schema: $ref: '#/definitions/Errors' 'default': description: Other error with any status code and response body format. definitions: Identification: type: object properties: appName: type: string description: Name of the application from Operator/Developer Cockpit example: "testapplication" appVersion: type: string description: Version of the application as given in Operation/Developer Cockpit. example: "1.0.0" hostTenant: type: string description: Tenant ID of the developer/operator tenant hosting the application. example: "testhosttenant1" userTenant: type: string description: Tenant ID of the tenant owning the data to be accessed with the Technical Token. example: "testusertenant1" AccessTokenResponse: type: object properties: access_token: type: string example: "eyJhbGciOi..." description: JWT bearer access Technical Token to access IoT data. token_type: type: string example: "bearer" description: "Type of the token provided by the API." timestamp: type: number example: "1559120938825" expires_in: type: integer format: int64 description: "Number of seconds before this token expires from the time of issuance." example: 1799 scope: type: string example: "cst.r uts.su im.usr.r em.rep.r tm.st.r tm.t.r agm.r iam-action.client_credentials.tenant-impersonation uts.ri asm.r atm.r uts.rc uaa.offline_token emds.ent.r asm.rep.r" jti: type: string description: The jti (JWT ID) claim provides a unique identifier for the JWT.The jti claim can be used to prevent the JWT from being replayed. The jti value is a case-sensitive string. example: 'b019ceb63513456c88f2d67c0e92d35b' TokensPayload: type: object required: - appName - appVersion - hostTenantId - userTenantIds properties: appName: type: string description: Name of the application from Operator/Developer Cockpit example: "testapplication" appVersion: type: string description: Version of the application as given in Operation/Developer Cockpit. example: "1.0.0" hostTenantId: type: string description: Tenant ID of the developer/operator tenant hosting the application. example: "testhosttenant1" userTenantIds: description: List of Tenant IDs of the tenants owning the data to be accessed with the Technical Token. type: array maxItems: 5 items: type: string example: [ "usertenanta", "usertenantb" ] TokensResponse: type: "object" properties: oauthTokens: type: array items: type: object properties: userTenantId: type: string description: Tenant ID of the tenant owning the data to be accessed with the Technical Token. example: "testusertenant1" token: $ref: '#/definitions/AccessTokenResponse' UserTenantResponse: type: "object" properties: page: $ref: '#/definitions/Page' userTenants: type: array items: type: object properties: id: type: string description: Tenant IDs provisioned by Developer/Operator tenant. example: testusertenant1 Page: type: object properties: size: type: integer totalElements: type: integer totalPages: type: integer number: type: integer Errors: type: object description: Error response body model. properties: errors: type: array description: "Concrete error codes and messages are defined at operation error response descriptions in this API specification." items: type: object properties: code: type: string description: "Unique error code. Every code is bound to one (parametrized) message." format: "mdsp.core.." example: "mdsp.core.keymanager.invalidAppNameFormat" logref: type: string description: "Logging correlation ID for debugging purposes." example: "0bff7e7a-cd25-4576-9908-4180ef086174" message: type: string description: "Human readable error message in English." example: "Example error message with parameter value 100" parameters: page: name: page in: query type: integer default: 0 description: Specifies the requested page index size: name: size in: query type: integer default: 500 & Max 500 description: Specifies the number of elements in a page. Maximum value for size is 100