# Link Identities

## Overview

For a user to request access to a resource in another application, sometimes an identity in this external application is required. For example, if you have a resource which controls access for your Github User to a Github Team, then Abbey needs a mechanism to link a user's central account (often their Abbey account, which is often email) to an identifier in the downstream system. 

For example:

* Github has [usernames](https://docs.github.com/en/enterprise-server@3.7/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/changing-your-github-username)
* AWS Identity Center has an [Identity Center ID](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html)
* etc 

We call this process linking. 

## What Does it Mean to Link Identities?

Linking an application identity is the process by which we associate the application's identity with your Abbey user. Once identity data has been linked for an external application, Abbey can use this identity data in its grant kits.

Below is an example of linking Github data into Abbey:

```
curl -X POST -d '{"type": "github", "data": {"username": "Alice"}}'
```

This links the Abbey user with Github, and lets Abbey know that the Github username for the Abbey user is "Alice". Now we can refer to this in a grant kit output block using the `user` object as follows:

```hcl
output = {
    location = "..."
    append = <<-EOT
      resource "github_team_membership" "eng_team_membership" {
        team_id = github_team.eng_team.id
        username = {{ .user.github.username }}
        role = "member"
      }
    EOT
}
```

Now when this grant kit is applied, Alice will become part of the `eng_team` Github team. Note that Github specific application information is found in `user.github` and a field named `username` contains the Github username you linked earlier.

## When do I need to link Identities?

By default Abbey provides access to your Abbey email in the `user` object as `user.email` for use in Grant Kits and policies. If the resource you're controlling access to only requires the email you signed up for Abbey with, then you don't need to link any application identity data!

## Which Applications does Abbey Linking with?

Abbey supports linking data from any external application! Abbey does however have first-class support for a set of applications which require linking application data in a specific way.

For more info about linking from first-class supported Abbey applications or just more information about Linking Application Identity Data in general, read [Linking Application Identities into Abbey](/reference/linking-application-identities-into-abbey.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.abbey.io/build-a-grant-kit/link-application-identity-data.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.