# Token

Manage Tokens

## Listing tokens

> Retrieves tokens based on the provided query.

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Token","description":"Manage Tokens"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agent_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"ai.text_manage":"Needed to execute actions related to the text generation.","ai.completion_manage":"Needed to execute actions related to the AI completions.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"schemas":{"TokenResponse":{"allOf":[{"$ref":"#/components/schemas/BaseToken"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the token."},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"BaseToken":{"type":"object","properties":{"name":{"type":"string","description":"Name of the token."}},"required":["name"]},"MetadataResponse":{"allOf":[{"$ref":"#/components/schemas/MetadataRequest"},{"type":"object","properties":{"createdAt":{"description":"Date and time when the object was created. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-31T13:18:02.379Z`","type":"string"},"modifiedAt":{"description":"Date and time when the object was last modified. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-31T13:18:02.379Z`","type":"string"}},"required":["version","createdAt","modifiedAt"]}]},"MetadataRequest":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the object. The version is required during the update operation because of the optimistic locking mechanism."}},"required":["version"]},"ErrorMessage":{"type":"object","properties":{"code":{"type":"integer"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}},"description":""},"ErrorMessageFault":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}},"responses":{"400_resp_common":{"description":"The request was syntactically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"403_resp_common":{"description":"Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}},"paths":{"/ai-service/{tenant}/agentic/tokens":{"get":{"summary":"Listing tokens","operationId":"GET-ai-list-tokens","responses":{"200":{"description":"List of tokens.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TokenResponse"}}}}},"400":{"$ref":"#/components/responses/400_resp_common"},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"}},"description":"Retrieves tokens based on the provided query.","tags":["Token"]}}}}
```

## Searching tokens

> Searches for tokens based on the provided query.

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Token","description":"Manage Tokens"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agent_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"ai.text_manage":"Needed to execute actions related to the text generation.","ai.completion_manage":"Needed to execute actions related to the AI completions.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"parameters":{"pageSize":{"schema":{"type":"string"},"in":"query","name":"pageSize","description":"The number of documents to be retrieved per page."},"pageNumber":{"schema":{"type":"string"},"in":"query","name":"pageNumber","description":"The page number to be retrieved. The size of the pages should be specified by the `pageSize` parameter."},"sort":{"schema":{"type":"string"},"in":"query","name":"sort","description":"List of properties used to sort the results, separated by colons."},"fields":{"schema":{"type":"string"},"in":"query","name":"fields","description":"Fields to be returned in the response."},"header_xTotalCount":{"schema":{"type":"boolean"},"in":"header","name":"X-Total-Count","description":"Flag indicating whether the total number of retrieved results should be returned."}},"schemas":{"TokenResponse":{"allOf":[{"$ref":"#/components/schemas/BaseToken"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the token."},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"BaseToken":{"type":"object","properties":{"name":{"type":"string","description":"Name of the token."}},"required":["name"]},"MetadataResponse":{"allOf":[{"$ref":"#/components/schemas/MetadataRequest"},{"type":"object","properties":{"createdAt":{"description":"Date and time when the object was created. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-31T13:18:02.379Z`","type":"string"},"modifiedAt":{"description":"Date and time when the object was last modified. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-31T13:18:02.379Z`","type":"string"}},"required":["version","createdAt","modifiedAt"]}]},"MetadataRequest":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the object. The version is required during the update operation because of the optimistic locking mechanism."}},"required":["version"]},"ErrorMessage":{"type":"object","properties":{"code":{"type":"integer"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}},"description":""},"ErrorMessageFault":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}},"QParamSearchBody":{"type":"object","properties":{"q":{"type":"string","description":"A standard query parameter is used to search for specific values. \n\nSee: [Standard Practices - Query parameter](https://developer.emporix.io/api-references/standard-practices/q-param)\n"}}}},"responses":{"400_resp_common":{"description":"The request was syntactically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"403_resp_common":{"description":"Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"requestBodies":{"QParamSearchBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QParamSearchBody"}}}}}},"paths":{"/ai-service/{tenant}/agentic/tokens/search":{"post":{"parameters":[{"$ref":"#/components/parameters/pageSize"},{"$ref":"#/components/parameters/pageNumber"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/header_xTotalCount"}],"summary":"Searching tokens","operationId":"POST-ai-search-tokens","responses":{"200":{"description":"List of tokens.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TokenResponse"}}}}},"400":{"$ref":"#/components/responses/400_resp_common"},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"}},"requestBody":{"$ref":"#/components/requestBodies/QParamSearchBody"},"description":"Searches for tokens based on the provided query.","tags":["Token"]}}}}
```

## Retrieving token by ID

> Retrieves the token by given ID.

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Token","description":"Manage Tokens"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agent_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"ai.text_manage":"Needed to execute actions related to the text generation.","ai.completion_manage":"Needed to execute actions related to the AI completions.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"parameters":{"fields":{"schema":{"type":"string"},"in":"query","name":"fields","description":"Fields to be returned in the response."}},"schemas":{"TokenResponse":{"allOf":[{"$ref":"#/components/schemas/BaseToken"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the token."},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}}]},"BaseToken":{"type":"object","properties":{"name":{"type":"string","description":"Name of the token."}},"required":["name"]},"MetadataResponse":{"allOf":[{"$ref":"#/components/schemas/MetadataRequest"},{"type":"object","properties":{"createdAt":{"description":"Date and time when the object was created. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-31T13:18:02.379Z`","type":"string"},"modifiedAt":{"description":"Date and time when the object was last modified. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-31T13:18:02.379Z`","type":"string"}},"required":["version","createdAt","modifiedAt"]}]},"MetadataRequest":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the object. The version is required during the update operation because of the optimistic locking mechanism."}},"required":["version"]},"ErrorMessageFault":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}},"ErrorMessage":{"type":"object","properties":{"code":{"type":"integer"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}},"description":""}},"responses":{"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"403_resp_common":{"description":"Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404_resp_common":{"description":"Example response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}},"paths":{"/ai-service/{tenant}/agentic/tokens/{tokenId}":{"get":{"parameters":[{"$ref":"#/components/parameters/fields"}],"summary":"Retrieving token by ID","operationId":"GET-ai-retrieve-token","responses":{"200":{"description":"A single token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"},"404":{"$ref":"#/components/responses/404_resp_common"}},"description":"Retrieves the token by given ID.","tags":["Token"]}}}}
```

## Upserting token

> Updates or creates a specified token by replacing all of its existing data with data from the request body.\
> If the \`metadata.version\` is provided then optimistic locking is enabled and version must match the version in the database.\
> \
> \*\*Important\*\*: The \`value\` field cannot be updated, once created token cannot change \`value\` field.

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Token","description":"Manage Tokens"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agent_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"ai.text_manage":"Needed to execute actions related to the text generation.","ai.completion_manage":"Needed to execute actions related to the AI completions.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"schemas":{"IdResponse":{"type":"object","properties":{"id":{"type":"string","description":"Identifier of the resource."}}},"ErrorMessage":{"type":"object","properties":{"code":{"type":"integer"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}},"description":""},"ErrorMessageFault":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}},"TokenRequest":{"allOf":[{"$ref":"#/components/schemas/BaseToken"},{"type":"object","properties":{"value":{"type":"string","description":"Value which represents token."},"metadata":{"$ref":"#/components/schemas/MetadataRequest"}},"required":["value"]}]},"BaseToken":{"type":"object","properties":{"name":{"type":"string","description":"Name of the token."}},"required":["name"]},"MetadataRequest":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the object. The version is required during the update operation because of the optimistic locking mechanism."}},"required":["version"]}},"responses":{"400_resp_common":{"description":"The request was syntactically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"403_resp_common":{"description":"Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404_resp_common":{"description":"Example response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"409_resp_common":{"description":"There are three possible reasons:\n 1. Resource with given code already exists, please choose unique code for your resource\n 2. Optimistic locking failed. If user sends metadata/version attribute which is outdated (someone else updated resource in the time user was performing his changes). User should retrieve the latest product data and retry the request.\n 3. Optimistic locking failed. User did not provide metadata/version attribute in update request, but someone else updated product while it was internally handled by product service. Resending the same request can result in successful update, but the update can override recently persisted changes.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"requestBodies":{"tokenUpsertBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequest"}}}}}},"paths":{"/ai-service/{tenant}/agentic/tokens/{tokenId}":{"put":{"summary":"Upserting token","operationId":"PUT-ai-upsert-token","responses":{"201":{"description":"ID of created token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdResponse"}}}},"204":{"description":"The resource has been successfully updated."},"400":{"$ref":"#/components/responses/400_resp_common"},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"},"404":{"$ref":"#/components/responses/404_resp_common"},"409":{"$ref":"#/components/responses/409_resp_common"}},"description":"Updates or creates a specified token by replacing all of its existing data with data from the request body.\nIf the `metadata.version` is provided then optimistic locking is enabled and version must match the version in the database.\n\n**Important**: The `value` field cannot be updated, once created token cannot change `value` field.","requestBody":{"$ref":"#/components/requestBodies/tokenUpsertBody"},"tags":["Token"]}}}}
```

## Deleting token

> Deletes tokens by given ID.\
> \
> \
> \*\*\*Important\*\*\*: If a token is being used by an agent or by an MCP server, then delete operation is not possible without \`force\` flag set to \`true\`.

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Token","description":"Manage Tokens"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agent_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"ai.text_manage":"Needed to execute actions related to the text generation.","ai.completion_manage":"Needed to execute actions related to the AI completions.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"parameters":{"force":{"schema":{"type":"boolean"},"in":"query","name":"force","description":"Allows you to remove a given entity even if it is used as a dependency in other entries. In that case, the removed entity is unassigned from other entries."}},"responses":{"400_resp_common":{"description":"The request was syntactically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"403_resp_common":{"description":"Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"schemas":{"ErrorMessage":{"type":"object","properties":{"code":{"type":"integer"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}},"description":""},"ErrorMessageFault":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}},"paths":{"/ai-service/{tenant}/agentic/tokens/{tokenId}":{"delete":{"parameters":[{"$ref":"#/components/parameters/force"}],"summary":"Deleting token","operationId":"DELETE-ai-delete-token","responses":{"204":{"description":"Given token has been deleted."},"400":{"$ref":"#/components/responses/400_resp_common"},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"}},"description":"Deletes tokens by given ID.\n\n\n***Important***: If a token is being used by an agent or by an MCP server, then delete operation is not possible without `force` flag set to `true`.","tags":["Token"]}}}}
```

## Partially updating token

> Partially updates a single token document with given information.\
> Single update may contain multiple partial updates in the form of an array. It contains the allowed operations list:\
>   \- \`add\` (adding an item to the items list)\
>   \- \`remove\` (removing an item from the items list)\
>   \- \`replace\` (replacing an item with given ID with new definition)\
> \
> \*\*Important\*\*: The \`value\` field cannot be updated, once created token cannot change \`value\` field.

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Token","description":"Manage Tokens"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agent_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"ai.text_manage":"Needed to execute actions related to the text generation.","ai.completion_manage":"Needed to execute actions related to the AI completions.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"responses":{"400_resp_common":{"description":"The request was syntactically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"403_resp_common":{"description":"Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404_resp_common":{"description":"Example response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"schemas":{"ErrorMessage":{"type":"object","properties":{"code":{"type":"integer"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}},"description":""},"ErrorMessageFault":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}},"PatchRequest":{"type":"array","description":"Partial update operation list.","items":{"type":"object","properties":{"op":{"anyOf":[{"enum":["ADD","REMOVE","REPLACE"]}],"type":"string"},"path":{"type":"string"},"value":{"anyOf":[{"type":"string","description":"Value of the string type."},{"type":"object","description":"Any part of the details object."}]}},"required":["op","path"]}}},"requestBodies":{"tokenPatchBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchRequest"}}}}}},"paths":{"/ai-service/{tenant}/agentic/tokens/{tokenId}":{"patch":{"summary":"Partially updating token","operationId":"PATCH-ai-update-token","responses":{"204":{"description":"No Content"},"400":{"$ref":"#/components/responses/400_resp_common"},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"},"404":{"$ref":"#/components/responses/404_resp_common"}},"description":"Partially updates a single token document with given information.\nSingle update may contain multiple partial updates in the form of an array. It contains the allowed operations list:\n  - `add` (adding an item to the items list)\n  - `remove` (removing an item from the items list)\n  - `replace` (replacing an item with given ID with new definition)\n\n**Important**: The `value` field cannot be updated, once created token cannot change `value` field.","requestBody":{"$ref":"#/components/requestBodies/tokenPatchBody"},"tags":["Token"]}}}}
```