openapi: 3.0.1 info: title: Client Service description: The client service provides a method for non-person ID login to the platform. version: '2.0' tags: - name: ClientService security: - Authorization: [] paths: /clients: get: summary: |- Return a list of clients Permission level: read operationId: ClientService_ListClients responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2ListClientsResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' parameters: - name: pageSize description: 'Page Size, Default: 10, Required: false' in: query required: false schema: type: integer format: int32 - name: pageToken description: 'MongoDB Field, describes the encoded page token for page traversal, Required: false' in: query required: false schema: type: string - name: tenantId description: 'Tenant of the clients, Required: false' in: query required: false schema: type: string - name: genericFilter description: |- Generic filter for clients fields (client_name, client_id, first_name, last_name) If it contains a whitespace, it splits the text and filter by both words, Required: false in: query required: false schema: type: string - name: sortField description: 'sort field, Default: client_name, Required: false' in: query required: false schema: type: string - name: sortType description: 'Sort Type for the results, Default: ASC, Required: false' in: query required: false schema: type: string enum: - NONE - ASC - DESC default: NONE tags: - ClientService post: summary: |- Creates a new client. It also onboards a user with no permissions for the client. Permission level: read-write operationId: ClientService_CreateClient responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2ClientResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' requestBody: content: application/json: schema: $ref: '#/components/schemas/v2CreateClientRequest' required: true tags: - ClientService /clients/login: post: summary: |- Generates a token for a client and returns it. This method does not require authorization, it is itself the method responsible for creating and returning a token. *NOTE: As stated in the description, the old GET /clients/{client_id}/login?client_secret={client_secret} endpoint will be deprecated as such please use the POST /clients/login endpoint with the cliendId and clientSecret in the body** operationId: ClientService_LoginClient2 responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2LoginClientResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' requestBody: content: application/json: schema: $ref: '#/components/schemas/v2LoginClientRequest' required: true tags: - ClientService /clients/logout: post: summary: |- Logout a token -- deletes it from Redis and Mongo. It also publishes a logout message to PubSub. Permission level: read-write operationId: ClientService_LogoutClient responses: '200': description: A successful response. content: application/json: schema: type: object properties: {} default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' tags: - ClientService /clients/oauth/token: post: summary: |- * Generates an OAuth2-compliant token for a client and returns it. The client credentials (clientId and clientSecret) must be passed in the Authorization header using Basic Authentication. description: |- This method adheres to the OAuth2 standard and provides a response containing the access token, expiration time, token type, and scope, along with additional authentication details. **Note**: This method does not require prior authorization as it is responsible for creating and returning the token itself. HTTP Mapping: - POST: /clients/oauth/token Security: - Requires Basic Authentication in the Authorization header. @return OAuth2TokenResponse containing the generated access token and related metadata. operationId: ClientService_GetOAuth2Token responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2OAuth2TokenResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' requestBody: content: application/json: schema: type: object properties: {} required: true tags: - ClientService security: - BasicAuth: [] /clients/qrcode: post: operationId: ClientService_CreateQRCode responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2CreateQRCodeResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' requestBody: content: application/json: schema: $ref: '#/components/schemas/v2CreateQRCodeRequest' required: true tags: - ClientService /clients/scim: delete: summary: |- Deactivates the SCIM token for a tenant without requiring the token itself. This allows customers to turn off SCIM even if they cannot retrieve the token from their IDP. The underlying SCIM client is preserved, so a new token can be created via CreateSCIMToken afterwards. Permission level: tenant-admin operationId: ClientService_DeactivateSCIMToken responses: '200': description: A successful response. content: application/json: schema: type: object properties: {} default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' parameters: - name: tenantId description: 'Tenant whose SCIM token should be deactivated, Required: false' in: query required: false schema: type: string tags: - ClientService post: operationId: ClientService_CreateSCIMToken responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2CreateSCIMTokenResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' requestBody: content: application/json: schema: $ref: '#/components/schemas/v2CreateSCIMTokenRequest' required: true tags: - ClientService /clients/scim/status: get: summary: |- Returns the status of the SCIM token for a tenant if it exists else, throws an exception. Permission level: tenant-admin operationId: ClientService_GetSCIMTokenStatus responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2GetSCIMTokenStatusResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' parameters: - name: tenantId description: |- Optional: Tenant whose SCIM token status should be retrieved. If omitted, the tenant is derived from the authenticated tenant context. in: query required: false schema: type: string tags: - ClientService /clients/search: post: operationId: ClientService_SearchClients responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2ListClientsResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' requestBody: content: application/json: schema: $ref: '#/components/schemas/v2SearchClientsRequest' required: true tags: - ClientService /clients/{clientIdentifier}: get: summary: |- Returns all the info of a client. Permission level: read operationId: ClientService_GetClient responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2ClientResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' parameters: - name: clientIdentifier description: 'Client Identifier of the client, can be of type CLIENT_ID or CLIENT_NAME, Required: true' in: path required: true schema: type: string - name: tenantId description: 'Tenant of the client to read, Required: false' in: query required: false schema: type: string - name: type description: |- Identifier Type to use to search for the client, Default: CLIENT_ID, Required: false - CLIENT_ID: Default value in: query required: false schema: type: string enum: - CLIENT_ID - CLIENT_NAME default: CLIENT_ID tags: - ClientService /clients/{clientId}: delete: summary: |- Deletes a client and everything related to it (all the tokens and the user). Permission level: read-write operationId: ClientService_DeleteClient responses: '200': description: A successful response. content: application/json: schema: type: object properties: {} default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' parameters: - name: clientId description: 'Client Id of the client to delete, Required: true' in: path required: true schema: type: string - name: tenantId description: 'Tenant of the client to delete, Required: false' in: query required: false schema: type: string tags: - ClientService put: summary: |- Updates a client. Client Name or Description can be updated with this method. Permission level: read-write operationId: ClientService_UpdateClient responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2ClientResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' parameters: - name: clientId description: 'Client Id of the client to update, Required: true' in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ClientServiceUpdateClientBody' required: true tags: - ClientService /clients/{clientId}/login: get: summary: |- Generates a token for a client and returns it. This method does not require authorization, it is itself the method responsible for creating and returning a token. *NOTE: As stated in the description, the old GET /clients/{client_id}/login?client_secret={client_secret} endpoint will be deprecated as such please use the POST /clients/login endpoint with the cliendId and clientSecret in the body** operationId: ClientService_LoginClient responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2LoginClientResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' parameters: - name: clientId description: 'Client Id of the client of which to generate a token, Required: true' in: path required: true schema: type: string - name: clientSecret description: 'Secret of the client to generate token, Required: false' in: query required: false schema: type: string tags: - ClientService /clients/{clientId}/secret: put: summary: |- Generates a new secret for the client. Permission level: read-write operationId: ClientService_UpdateClientSecret responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2ClientResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' parameters: - name: clientId description: 'Client Id of the client of which to create a new secret, Required: true' in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ClientServiceUpdateClientSecretBody' required: true tags: - ClientService servers: - url: https://prod-ui-zwseuprod01p.pp.zebra.com/api description: EU Server - url: https://prod-ui-zwsusprod01p.pp.zebra.com/api description: NA Server components: schemas: ClientServiceUpdateClientBody: type: object properties: tenantId: type: string title: 'Tenant of the client, Required: false' clientName: type: string title: 'Updated name of the client, Required: false' clientDescription: type: string title: 'Updated client description, Required: false' updateFieldMask: type: string title: |- FieldMask to control what fields are to be updated, Required: true Valid path names are `client_name`, `client_description`,`assigned_roles`, and/or `token_ttl` timeToLive: $ref: '#/components/schemas/v2TimeToLive' tokenTtl: $ref: '#/components/schemas/v2TimeToLive' primarySite: type: string title: 'The primary site that the client is assigned to, the tenantId of the site is inferred to be the same as the client, Required: false' assignedRoles: type: array items: $ref: '#/components/schemas/v2RoleProto' title: 'Roles associated with the client, Required: false' ClientServiceUpdateClientSecretBody: type: object properties: tenantId: type: string title: 'Tenant of the client, Required: false' clientV2Status: type: string enum: - NONE - ACTIVE - INACTIVE default: NONE title: '- NONE: Default Value' commonsSortType: type: string enum: - NONE - ASC - DESC default: NONE googleRpcStatus: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: $ref: '#/components/schemas/protobufAny' protobufAny: type: object properties: '@type': type: string additionalProperties: {} v2AuthenticationProto: type: object properties: tenantId: type: string title: Tenant of the associated token userId: type: string title: User Id of the associated token expiresIn: type: string format: int64 title: TTL of the associate token (in seconds) permissions: type: array items: $ref: '#/components/schemas/v2PermissionResponse' title: List of permissions associated with the token email: type: string title: Email address of the user title: Main Auth Model v2ClientResponse: type: object properties: tokenMetadata: $ref: '#/components/schemas/v2TokenMetadataProto' v2CreateClientRequest: type: object properties: clientName: type: string title: 'Name of the client, Required: true' tenantId: type: string title: 'Tenant of the client, Required: false' timeToLive: $ref: '#/components/schemas/v2TimeToLive' firstName: type: string title: 'Client''s first name, Required: false' lastName: type: string title: 'Client''s last name, Required: false' clientDescription: type: string title: 'Client''s Description, Required: false' tokenTTL: $ref: '#/components/schemas/v2TimeToLive' primarySite: type: string title: 'The primary site that the client is assigned to, the tenantId of the site is inferred to be the same as the client, Required: false' assignedRoles: type: array items: $ref: '#/components/schemas/v2RoleProto' title: 'Roles associated with the client, Required: false' title: Requests and Responses v2CreateQRCodeRequest: type: object properties: tenantId: type: string title: 'Tenant of the client, Required: false' timeToLive: $ref: '#/components/schemas/v2TimeToLive' firstName: type: string description: 'Client''s first name. Required: false.' lastName: type: string description: 'Client''s last name. Required: false.' clientDescription: type: string title: 'Client''s description, Required: false' v2CreateQRCodeResponse: type: object properties: clientId: type: string title: The client ID -- Randomly generated String data: type: string description: |- The data that will be used to build the QR Code. For now it will be a URL pointing to the REST layer of client-service (LoginClient rpc method) where the user can just scan the QR Code and get a Phoenix token. v2CreateSCIMTokenRequest: type: object properties: tenantId: type: string title: 'Tenant of the associated token, Required: false' v2CreateSCIMTokenResponse: type: object properties: scimToken: type: string title: SCIM token v2GetSCIMTokenStatusResponse: type: object properties: expiresAt: type: string format: date-time description: Timestamp of the latest active SCIM bearer token expiry. v2IdentifierType: type: string enum: - CLIENT_ID - CLIENT_NAME default: CLIENT_ID title: '- CLIENT_ID: Default value' v2ListClientsResponse: type: object properties: tokensMetadata: type: array items: $ref: '#/components/schemas/v2TokenMetadataProto' title: List of Clients in the current page nextPageToken: type: string title: next page token v2LoginClientRequest: type: object properties: clientId: type: string title: 'Client Id of the client of which to generate a token, Required: true' clientSecret: type: string title: 'Secret of the client to generate token, Required: false' v2LoginClientResponse: type: object properties: token: type: string title: Token generated for the client authentication: $ref: '#/components/schemas/v2AuthenticationProto' v2OAuth2TokenResponse: type: object properties: access_token: type: string title: Access Token generated for the client expires_in: type: string format: int64 title: TTL of the associate token (in seconds) token_type: type: string description: Defines the tokenType. As per OAuth 2.0 specification, the value is "Bearer" for access tokens. v2PermissionResponse: type: object properties: permissionId: type: string title: Generated at the time of creation (Randomly generated String) ownerTenantId: type: string description: Owner tenant of the permission to which it belongs. friendlyId: type: string title: 'A unique identifier of a permission in a tenant, Required: false' domain: type: string title: 'The platform domain (example: zpa, reflexis, wfc)' scope: type: string title: Some more general scoping for the data (like a particular app in the domain) description: type: string title: Permission Description type: type: string title: 'Type of Permission (example: user, phoenixAuth, permission, *)' grants: type: string title: 'Grants to Permission (example: admin, r, rw, *)' tenants: type: string title: 'Tenants to which permission belongs to. (example: *, ^ or comma-separated list of tenants)' targets: type: array items: $ref: '#/components/schemas/v2TargetProto' title: targets for permission roles: type: array items: $ref: '#/components/schemas/v2UniqueRoleProto' title: List of roles that have this permission users: type: array items: $ref: '#/components/schemas/v2UniqueUserProto' title: List of users that have this permission systemLevel: type: boolean title: |- Used to specify whether permission is a system_level permission or not. A system level permission cannot be deleted. System level means something Phoenix needs to function and only should be created by services or trained Zebra employee's groupIds: type: array items: type: string title: Permission group IDs deactivated: type: boolean title: 'Option to control if the permission is deactivated, Required: false' creationTime: type: string format: date-time title: Time of creation of permission entity lastUpdated: type: string format: date-time title: Time of most recent update to the permission entity typeFriendlyName: type: string description: Friendly name of the type of permission. Blank if not set. scopeFriendlyName: type: string description: Friendly name of the scope of the permission. Blank if not set. grantFriendlyName: type: string description: Friendly name of the grant from PERMISSION_GRANTS property. Blank if not set. grantDescription: type: string description: Description of the grant from PERMISSION_GRANTS property. Blank if not set. title: Main Permission data model v2RoleProto: type: object properties: domain: type: string description: |- The platform domain. Required: true. (e.g. ZPA, Reflexis, WFC) Defaults to the domain in the request. scope: type: string description: 'Some more general scoping for the data (like a particular app in the domain). Required: false.' roleId: type: string description: 'The role ID. Required: true.' v2SearchClientsRequest: type: object properties: tenantId: type: string title: 'Tenant of the clients, Required: false' clientName: type: string title: 'Client Name to search for, Required: false' primarySite: type: string title: 'Primary Site associated with the client, Required: false' tokenTtlUnit: $ref: '#/components/schemas/v2TimeToLiveUnit' specificFilter: type: array items: $ref: '#/components/schemas/v2RoleProto' title: 'Role filter to search clients by associated roles, Required: false' status: $ref: '#/components/schemas/clientV2Status' pageSize: type: integer format: int32 title: 'Page Size, Default: 10, Required: false' pageToken: type: string title: 'MongoDB Field, describes the encoded page token for page traversal, Required: false' sortField: type: string title: 'sort field, Default: client_name, Required: false, Allowed values: clientName' sortType: $ref: '#/components/schemas/commonsSortType' partialSearch: type: boolean title: 'Partial match flag, if true performs a partial match search on client_name, Required: false' v2TargetProto: type: object properties: idType: type: string title: The ID type of what the target applies to. Typically in the form by{{Thing}} id: type: string description: The value that the target applies to. description: |- Targets describe what the permission applies to. For example if you wanted to have an admin permission and wanted the user to only have permissions on unitA and unitB you would design your target like this: id_type = "byUnit" id = "unitA,unitB" The actual values used are free form and determined by the application when designing their authorization model. Some standards we try to stick to despite the free form are: id_type we try and model with by{{Thing}}. The most common use case for this is byTenant (which we moved up to the base permission level, see permission.proto). For ID, which is the actual value this is giving access to we recommend using: * - if the user should have access to everything in that Thing. so a byTenant - * permission would give access to ALL tenants. ^ - gives access to the user's own Thing. For example - byTenant - ^ would give access to the user's own tenant. This gives the ability to create a single permission that can be used by multiple roles. Otherwise we use a specific value, so byTenant - mytenant would give access to the "mytenant" tenant. This is best used for giving access to someone outside of our tenant to your tenant, or if you have a list of specific things that wont change depending on who has access to the permission. v2TimeToLive: type: object properties: value: type: integer format: int32 title: Numeric Value of TTL unit: $ref: '#/components/schemas/v2TimeToLiveUnit' v2TimeToLiveUnit: type: string enum: - FOREVER - HOUR - DAY - WEEK - MONTH default: FOREVER description: '- FOREVER: Default Value' title: Enum representing Unit of TTL v2TokenMetadataProto: type: object properties: clientName: type: string title: Name of the client clientId: type: string title: Generated at the time of creation. (Randomly generated String) tenantId: type: string title: tenant of the client createTime: type: string format: date-time title: Time of creation of client lastUpdate: type: string format: date-time title: Time of most recent update of client expirationTime: type: string format: date-time title: Time till which client is valid firstName: type: string title: Client first name lastName: type: string title: Client last name secret: type: string title: Client Secret clientDescription: type: string title: Client Description tokenTtl: type: string format: int64 title: TokenTTL of the client in seconds tokenTtlUnit: type: string title: Token expiration unit FOREVER/HOUR/DAY/WEEK/MONTH/YEAR primarySite: type: string title: Primary site associated with the client assignedRoles: type: array items: $ref: '#/components/schemas/v2RoleProto' title: Roles associated with the client status: $ref: '#/components/schemas/clientV2Status' clientTtl: type: string format: int64 title: Client expiration duration in seconds (time between creation and expiration) clientTtlUnit: type: string title: Client expiration unit FOREVER/HOUR/DAY/WEEK/MONTH/YEAR title: Proto Models v2UniqueRoleProto: type: object properties: tenantId: type: string description: 'The ID of the tenant. Required: false. Defaults to the tenant of the user making the call.' domain: type: string description: |- The platform domain. Required: true. (e.g. ZPA, Reflexis, WFC) Defaults to the domain in the request. scope: type: string description: 'Some more general scoping for the data (like a particular app in the domain). Required: false.' roleId: type: string description: 'The role ID. Required: true.' userIds: type: array items: type: string title: 'The User Ids for the Unique Role Proto, Required: false' v2UniqueUserProto: type: object properties: tenantId: type: string description: 'The ID of the tenant. Required: false. Defaults to the tenant of the user making the call.' userId: type: string description: 'The user ID. Required: true.' firstName: type: string description: 'The first name. Required: false.' lastName: type: string description: 'The last name. Required: false.' securitySchemes: Authorization: type: apiKey description: Bearer token name: Authorization in: header