Working with Identities and Names

Every identity in the globaliD system has a UUID associated with it that uniquely identifies this particular identity. This UUID is often referred to as the identity's gid_uuid value.

An identity also has a unique globaliD name associated with it. Every name can only belong to one identity at a time, though the same name can be owned by different identities over time. For example, the globaliD name john might be owned by the identity with a gid_uuid value of d58f094f-6d28-4aa1-9bf9-afe517c396b9. This identity might then release the name, so that the name is not associated with an identity at all. Sometime later, another identity, a202251c-fbfb-4e12-9b2a-3c46761c7c36, might claim the same name.

This association of globaliD names to identities is fundamental to the way globaliD operates. All of the API endpoints which deal with identities refer to an identity by its UUID value. Since the end user never knows (or cares) about an identity's UUID value, as a developer you will have to know how to translate from a gid_uuid into a name, and vice versa.

To find the UUID of the identity currently associated with a given globaliD name, you can call the /v1/identities API endpoint. This endpoint is public, and so does not require an access token. To call it, simply make an HTTP GET request to the /v1/identities endpoint. The body of the HTTP request should look like this:

    {
      "gid_name": "<DESIRED_NAME>"
    }

The response will contain the identity with that name, like this:

    {
      "data": [
        {
          "gid_uuid": "d58f094f-6d28-4aa1-9bf9-afe517c396b9",
          "status": "in_use",
          ...
        }
      ],
      ...
    }

As the name of this endpoint suggests, you can use it for much more than just finding the gid_uuid associated with a given globaliD name. You can search for matching names using a wide range of search criteria, and the API will return all matching identities. The information returned also includes far more than just the gid_uuid of the matching identit(ies) -- all the public profile information for the identity is returned as well.

If the given name has never been used, then the returned data array will be empty. If the name has been released (so that it no longer belongs to the given identity), then the returned identity will have a status value of "released".

Using this endpoint, it is easy to translate a given globaliD name into the gid_uuid value for the associated identity. It is also possible to go the other way, by retrieving the name associated with a given gid_uuid value. To do this, call the GET /v1/identities/<gid_uuid> endpoint, replacing <gid_uuid> with the UUID of the identity you want to get information about. If the endpoint responds with 200 (OK), then the body of the response will contain all the public information about the given identity, including the identity's globaliD name and the current status of the identity:

    HTTP/1.1 200 OK

    {
      "gid_name": "jsmith",
      "status": "in_use",
      ...
    }

If there is no identity with that UUID value, then a 404 (Not Found) error will be returned instead.

The GET /v1/identities/<gid_uuid> endpoint is public; you do not need an access token to call it.

Finally, to find the gid_uuid and name for the identity associated with an access token, you can call the GET /v1/identities/me endpoint:

Request:

    POST /v1/identities/me
    BEARER <access_token>

Response:

    HTTP/1.1 200 OK

    {
      "gid_uuid": "d58f094f-6d28-4aa1-9bf9-afe517c396b9",
      "gid_name": "jsmith",
      "type": "individual",
      "status": "in_use",
      "created_at": "2019-04-03t21:19:12z",
      "released_at": null,
      "completed": true,
      "public_signing_key": "...",
      "public_encryption_key": "...",
      "purpose_personal": false,
      "purpose_professional": true,
      "purpose_recreational": false,
      "display_name": "John Smith",
      "description": "Professional carpenter based in San Jose, CA",
      "display_image_url": "...",
      "region_code": "NM",
      "region_name": "North America",
      "country_code": "USA",
      "country_name": "United States",
      "state_code": "USA-CA",
      "state_name": "California",
      "metro_code": "USA-CA-SFO",
      "metro_name": "San Francisco"
    }

As you can see, all the public information about the identity is returned.