# Get the attribute mappings of a connection

`GET /v1/connections/{connection_id}/attribute-mappings` · permission `connections:read`

Returns the attribute mapping rules of an enterprise (SAML or OIDC) connection, ordered by target. Each rule maps an attribute or claim sent by the identity provider (`source_name`) to a user field (`target`). The `ETag` header carries the version of the list; send it as `If-Match` when you replace the list or apply a preset profile. A connection without stored rules returns an empty list: at sign-in the template default applies (the `generic` profile for OIDC; nothing is mapped for SAML). Reads are not audited.

## Request

| Field | Type | Required | Description |
|---|---|---|---|
| `connection_id` | path | yes | Enterprise connection ID (`conn_…`). |

## Response

`200 OK` with the list and an `ETag`.

```json
{
  "attribute_mappings": [
    {
      "target": "email",
      "source_name": "email",
      "source_name_format": null,
      "overwrite": "always",
      "profile": "okta"
    },
    {
      "target": "user_metadata.department",
      "source_name": "department",
      "source_name_format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
      "overwrite": "if_empty",
      "profile": "generic"
    }
  ]
}
```

| Field | Description |
|---|---|
| `target` | `email`, `given_name`, `family_name`, `name`, `locale`, `zoneinfo`, `phone`, `groups` or `user_metadata.<key>`. |
| `source_name` | SAML attribute `Name` or OIDC claim name (dotted path, depth ≤ 3). |
| `source_name_format` | SAML `NameFormat` the attribute is read with; `null` matches by name only. |
| `overwrite` | `always` (every sign-in), `if_empty` (only when the field is empty) or `never` (only at creation). |
| `profile` | Preset the rule came from; `generic` for rules written by hand. |

## Errors

| HTTP | code | When |
|---|---|---|
| 404 | `not_found` | The connection does not exist in this environment or is not an enterprise connection. |
| 401 | `unauthenticated` | The credential is missing, invalid or revoked. |
| 403 | `insufficient_permissions` | The credential lacks the required permission. |
| 429 | `rate_limited` | The rate limit was exceeded; retry after the `Retry-After` period. |
| 503 | `service_unavailable` | A dependency is temporarily unavailable; retry after the `Retry-After` period. |

## Example

```bash
curl -i "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/attribute-mappings" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"
```

```bash
keenauth connections attribute-mappings get conn_01j9xp6q0r1s5t7v9w1x3y5z7b
```