# Resolve Twin Identity
This endpoint returns a list of Twin UUIDs (if the details parameter is set to False) or the details of Twins (if the details parameter is set to True):
- If the
detailsparameter is set toFalse(default value) all Twin UUIDs to which a given Identity is attached (if the Identity is visible to the calling user) are returned, regardless of whether the Twin is visible to the calling user. - If the
detailsparameter is set toTrue, the details of Twins to which a given Identity is attached (if the Identity is visible to the calling user) are returned. Only Twins visible to the calling user are returned. Please see the sections requestdetails=Trueand responsedetails=Truefor more details.
When resolving an Identity, the user can provide additional context for the resolution process to narrow down their search.
IMPORTANT NOTE
The search might result costly and time-consuming if you do not narrow down the context of your search. We highly recommend that you keep the context of the search as narrow as possible or to cache the response. You can narrow down the context by using the query string parameter context.
| Method | Path | Operation* |
|---|---|---|
| GET | /resolve/{identity} | resolve_twin_identity |
*
In order for a user to perform the "resolve_twin_identity" operation, the "resolve_twin_identity" permission must be included in the list of allowed actions in the statement of the user's role.
# Request
| Parameter | Type | In | Description |
|---|---|---|---|
| {identity} required | string | path | User-defined ID for the Identity. It must match the regular expression(opens new window) ^[A-Za-z_][0-9A-Za-z_]{0,7}#[0-9A-Za-z_=+-]{1,128}$. It is stored in the "identity" field of the creation certificate of the Identity. |
| context optional * | string (value is {account}, personal, or system); or list (value is list of {account} values); DEFAULT=personal | query string | As it is possible to use the same Identity to group several Twins, you can provide additional context to narrow down the list of Identities to be included in the search: - {account}: Account UUID. Identities owned by the specified account and visible to the requesting user.- personal: Identities owned by the account of the requesting user.- system: Identities in the entire Trusted Twin system visible to the requesting user.-list of {account} values: List of account UUIDs. Identities owned by the specified account and visible to the requesting user. |
| details optional ** | boolean, DEFAULT=False | query string | Denotes whether the details of each Twin should be returned. |
*
The "context" parameter is optional and does not need to be included in the request body when resolving Identities. If it is not included in the request, its default value is used.
**
The "details" parameter is optional and does not need to be included in the query string of the request. If it is not included in the request, a list of Twin UUIDs is returned.
# Response
# Request (details=True)
| Parameter | Type | In | Description |
|---|---|---|---|
| {identity} required | string | path | User-defined ID for the Identity. It must match the regular expression(opens new window) ^[A-Za-z_][0-9A-Za-z_]{0,7}#[0-9A-Za-z_=+-]{1,128}$. It is stored in the "identity" field of the creation certificate of the Identity. |
| context optional * | string, value is {account}, personal, or system; DEFAULT=personal | query string | As it is possible to use the same Identity to group several Twins, you can provide additional context to narrow down the list of Identities to be included in the search: - {account}: Account UUID. Identities owned by the specified account and visible to the requesting user.- personal: Identities owned by the account of the requesting user.- system: Identities in the entire Trusted Twin system visible to the requesting user. |
| details optional ** | boolean, DEFAULT=False | query string | Denotes whether the details of each Twin should be returned. |
*
The "context" parameter is optional and does not need to be included in the request body when resolving Identities. If it is not included in the request, its default value is used.
**
The "details" parameter is optional and does not need to be included in the query string of the request. If it is not included in the request, a list of Twin UUIDs is returned.
# Response (details=True)
| Attribute | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| owner | string | Account UUID of the account which is the current owner of the Twin. The ownership of a Twin can be transferred. | ||||||||||||
| status | string, value is "alive" or "terminated" | The status of a Twin can be "alive" or "terminated". In case of alive Twins, the "description" can be updated by the owner of the Twin. In case of terminated Twins, the description field cannot be updated. Ledger Entries, Identities, and Docs can be attached to alive and terminated Twins by all users involved in the process. | ||||||||||||
| updated_ts | timestamp | Time at which the Twin was last updated. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window). | ||||||||||||
| description | dictionary | Attributes of the Twin defined by the owner in form of key-value pairs: - key: It must match the regular expression(opens new window) ^[a-z_][0-9a-z_]{0,63}$.- value: JSON compliant value. Only the owner of the Twin can update the description of the Twin. For more details consult the description field section. | ||||||||||||
| creation_certificate | dictionary | Certificate generated automatically by the system upon creation of a Twin. It cannot be modified after it has been generated.
| ||||||||||||
| termination_certificate | dictionary | Certificate generated automatically by the system when a Twin is terminated. It cannot be modified after it has been generated.
|
# Status codes
Requests to this endpoint result in generic status codes. For a comprehensive list of status codes, please consult the Status codes section.
Was this article helpful?