> For the complete documentation index, see [llms.txt](https://docs.bird.com/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bird.com/api/accounts-api/api-reference/organizations/access-keys.md).

# Access keys

## List access keys

> List the access keys that are created for this organization.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization credentials.","name":"organization_access_key"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"parameters":{"limit":{"name":"limit","description":"Limits the number of results to return","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},"cursor":{"name":"pageToken","description":"Pagination token that keeps of track of the current position in the list","in":"query","schema":{"type":"string"}},"direction":{"name":"reverse","description":"Order in which to retrieve the results","in":"query","schema":{"type":"boolean","default":false}}},"schemas":{"AccessKeyList":{"type":"object","title":"AccessKeyList","properties":{"results":{"type":"array","description":"List of access keys.","items":{"$ref":"#/components/schemas/AccessKeyListItem"}}},"required":["results"]},"AccessKeyListItem":{"type":"object","additionalProperties":false,"title":"AccessKey","description":"The access key record.","properties":{"id":{"type":"string","description":"ID of the access key."},"organizationId":{"type":"string","description":"ID of the organization that owns the access key."},"name":{"$ref":"#/components/schemas/AccessKeyName"},"type":{"$ref":"#/components/schemas/AccessKeyType"},"description":{"$ref":"#/components/schemas/AccessKeyDescription"},"suffix":{"$ref":"#/components/schemas/AccessKeySuffix"},"lastUsedAt":{"type":"string","format":"date-time","description":"When the access key was last used.","nullable":true},"createdAt":{"type":"string","format":"date-time","description":"When the access key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the access key was last updated."},"roleIds":{"type":"array","uniqueItems":true,"deprecated":true,"description":"IDs of IAM roles attached to the access key.","items":{"type":"string"},"minItems":0,"maxItems":5},"roleRefs":{"type":"array","uniqueItems":true,"description":"The list of IAM roles assigned to the access key.","items":{"$ref":"#/components/schemas/iam_role_ref"},"minItems":0,"maxItems":5}},"required":["id","organizationId","name","suffix","createdAt"]},"AccessKeyName":{"type":"string","description":"Access key name.","minLength":1,"maxLength":256},"AccessKeyType":{"type":"string","enum":["user","workspace","workspace-scim","service","organization"]},"AccessKeyDescription":{"type":"string","description":"Access key description.","minLength":1,"maxLength":256},"AccessKeySuffix":{"type":"string","description":"Access key suffix.","minLength":6,"maxLength":6},"iam_role_ref":{"type":"object","title":"RoleReference","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["organization","managed"]},"workspaces":{"nullable":true,"type":"array","items":{"type":"string","format":"uuid"}}},"required":["id","type"]},"responseBody":{"type":"object","title":"PaginatedList","description":"A list of results that supports pagination.","properties":{"nextPageToken":{"type":"string","description":"The token to fetch the next page of results. If empty, there are no more results to fetch."}}},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"}}},"paths":{"/organizations/{organizationId}/access-keys":{"get":{"description":"List the access keys that are created for this organization.","operationId":"listAccessKeys","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/direction"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AccessKeyList"},{"$ref":"#/components/schemas/responseBody"}]}}},"description":"OK"},"404":{"$ref":"#/components/responses/notFound"}},"summary":"List access keys","tags":["organization_access_key"]}}}}
```

## Create access key

> Create a new access key for the organization.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization credentials.","name":"organization_access_key"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"CreateAccessKey":{"type":"object","additionalProperties":false,"title":"CreateAccessKey","required":["name","description"],"properties":{"name":{"$ref":"#/components/schemas/AccessKeyName"},"description":{"$ref":"#/components/schemas/AccessKeyDescription"},"roleIds":{"type":"array","description":"IAM roles attached to this access key.","deprecated":true,"items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":5},"roleRefs":{"type":"array","uniqueItems":true,"description":"The list of IAM roles to assign to the access key.","items":{"$ref":"#/components/schemas/iam_role_ref"},"minItems":1,"maxItems":5}}},"AccessKeyName":{"type":"string","description":"Access key name.","minLength":1,"maxLength":256},"AccessKeyDescription":{"type":"string","description":"Access key description.","minLength":1,"maxLength":256},"iam_role_ref":{"type":"object","title":"RoleReference","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["organization","managed"]},"workspaces":{"nullable":true,"type":"array","items":{"type":"string","format":"uuid"}}},"required":["id","type"]},"AccessKeyListItem":{"type":"object","additionalProperties":false,"title":"AccessKey","description":"The access key record.","properties":{"id":{"type":"string","description":"ID of the access key."},"organizationId":{"type":"string","description":"ID of the organization that owns the access key."},"name":{"$ref":"#/components/schemas/AccessKeyName"},"type":{"$ref":"#/components/schemas/AccessKeyType"},"description":{"$ref":"#/components/schemas/AccessKeyDescription"},"suffix":{"$ref":"#/components/schemas/AccessKeySuffix"},"lastUsedAt":{"type":"string","format":"date-time","description":"When the access key was last used.","nullable":true},"createdAt":{"type":"string","format":"date-time","description":"When the access key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the access key was last updated."},"roleIds":{"type":"array","uniqueItems":true,"deprecated":true,"description":"IDs of IAM roles attached to the access key.","items":{"type":"string"},"minItems":0,"maxItems":5},"roleRefs":{"type":"array","uniqueItems":true,"description":"The list of IAM roles assigned to the access key.","items":{"$ref":"#/components/schemas/iam_role_ref"},"minItems":0,"maxItems":5}},"required":["id","organizationId","name","suffix","createdAt"]},"AccessKeyType":{"type":"string","enum":["user","workspace","workspace-scim","service","organization"]},"AccessKeySuffix":{"type":"string","description":"Access key suffix.","minLength":6,"maxLength":6},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}},"DetailedError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"},"details":{"type":"object","description":"Detailed information on where the error exists, usually the field name on the request payload","additionalProperties":{"type":"array","description":"The error description for the specific detail","items":{"type":"string"}}}}}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"},"invalidRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedError"}}},"description":"Request validation failed"}}},"paths":{"/organizations/{organizationId}/access-keys":{"post":{"description":"Create a new access key for the organization.","operationId":"createAccessKey","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAccessKey"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"accessKey":{"$ref":"#/components/schemas/AccessKeyListItem"},"token":{"description":"The token that can be used for authentication","maxLength":36,"minLength":36,"type":"string"}},"required":["accessKey","token"],"type":"object"}}},"description":"Created"},"404":{"$ref":"#/components/responses/notFound"},"422":{"$ref":"#/components/responses/invalidRequest"}},"summary":"Create access key","tags":["organization_access_key"]}}}}
```

## Get access key

> Retrieve a single access key.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization credentials.","name":"organization_access_key"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"AccessKey":{"type":"object","title":"AccessKey","description":"The access key record.","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"ID of the access key."},"organizationId":{"type":"string","format":"uuid","description":"ID of the organization that owns the access key."},"name":{"$ref":"#/components/schemas/AccessKeyName"},"type":{"$ref":"#/components/schemas/AccessKeyType"},"description":{"$ref":"#/components/schemas/AccessKeyDescription"},"suffix":{"$ref":"#/components/schemas/AccessKeySuffix"},"lastUsedAt":{"type":"string","format":"date-time","description":"When the access key was last used.","nullable":true},"createdAt":{"type":"string","format":"date-time","description":"When the access key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the access key was last updated."},"roles":{"type":"array","description":"IAM roles attached to this access key.","items":{"$ref":"#/components/schemas/iam_role"},"minItems":0,"maxItems":5}},"required":["id","organizationId","name","suffix","createdAt","roles"]},"AccessKeyName":{"type":"string","description":"Access key name.","minLength":1,"maxLength":256},"AccessKeyType":{"type":"string","enum":["user","workspace","workspace-scim","service","organization"]},"AccessKeyDescription":{"type":"string","description":"Access key description.","minLength":1,"maxLength":256},"AccessKeySuffix":{"type":"string","description":"Access key suffix.","minLength":6,"maxLength":6},"iam_role":{"type":"object","title":"Role","additionalProperties":false,"properties":{"id":{"type":"string","description":"ID of the role.","format":"uuid"},"organizationId":{"type":"string","description":"ID of the organization to which this role belongs.","format":"uuid"},"name":{"type":"string","description":"Role name."},"description":{"type":"string","description":"Role description."},"type":{"type":"string","description":"Whether this role is managed by MessageBird or by the organization.","enum":["organization","managed"]},"policies":{"type":"array","description":"IAM Policies this role contains.","items":{"oneOf":[{"$ref":"#/components/schemas/iam_policy"},{"$ref":"#/components/schemas/iam_policy_ref"}]}},"usersDependencyCount":{"type":"integer","description":"The number of users this role is assigned to.","minimum":0},"accessKeysDependencyCount":{"type":"integer","description":"The number of access keys this role is assigned to.","minimum":0},"createdAt":{"type":"string","format":"date-time","description":"When this role was created."},"updatedAt":{"type":"string","format":"date-time","description":"When this role was last updated."},"metadata":{"type":"object","description":"Metadata for the IAM Role.","nullable":true,"additionalProperties":false,"properties":{"clouds":{"$ref":"#/components/schemas/clouds"}}},"actions":{"type":"array","description":"Actions this role contains.","nullable":true,"items":{"$ref":"#/components/schemas/iam_action"}}},"required":["id","name","type","policies","usersDependencyCount","accessKeysDependencyCount","createdAt","updatedAt"]},"iam_policy":{"type":"object","title":"Policy","description":"The IAM policy record.","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"ID of the IAM Policy."},"name":{"type":"string","description":"IAM Policy name."},"description":{"type":"string","description":"IAM Policy description."},"definitions":{"type":"array","title":"PolicyDefinitions","description":"List of IAM Policy definitions.","items":{"type":"object","title":"PolicyDefinition","description":"An access rule for a specific resource and action.","additionalProperties":false,"properties":{"effect":{"type":"string","enum":["allow","deny"],"description":"The outcome of the definition if a combination of the resources and actions match."},"resources":{"type":"array","description":"A list of resources","items":{"type":"string"}},"actions":{"type":"array","description":"A list of actions","items":{"type":"string","enum":["any","view","create","delete","update"]}},"conditionsAll":{"type":"array","items":{"type":"object","title":"PolicyConditionAll","additionalProperties":false,"properties":{"any":{"type":"object","title":"PolicyConditionAny","additionalProperties":{"type":"object","additionalProperties":{"type":"string","maxLength":256}}}}}}},"required":["effect","resources","actions"]},"minItems":1,"maxItems":240},"rolesDependencyCount":{"type":"integer","description":"The number of IAM Roles that depend on this IAM policy.","minimum":0},"usersDependencyCount":{"type":"integer","description":"The number of users that depend on this IAM policy.","minimum":0},"scope":{"type":"string","description":"The scope to which this policy applies.","enum":["organization","root"]},"type":{"type":"string","description":"The type of policy, managed indicates it's controlled by the platform.","enum":["managed","organization"]},"createdAt":{"type":"string","format":"date-time","description":"When the IAM Policy was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the IAM Policy was last updated."},"metadata":{"type":"object","description":"Metadata for the IAM Policy.","nullable":true,"additionalProperties":false,"properties":{"clouds":{"$ref":"#/components/schemas/clouds"},"apps":{"$ref":"#/components/schemas/apps"},"groups":{"$ref":"#/components/schemas/groups"}}}},"required":["id","name","definitions","scope","createdAt","updatedAt"]},"clouds":{"type":"array","nullable":true,"items":{"type":"string","enum":["platform","customer-service","marketing","process-automation","ai-hub","payments","developer","admin","hr","sales","expenses"]}},"apps":{"type":"array","nullable":true,"items":{"type":"string","enum":["inbox","campaigns","flows","journeys","studio","analytics","channels","numbers","bots","contacts"]}},"groups":{"type":"array","nullable":true,"items":{"type":"string"}},"iam_policy_ref":{"type":"object","title":"PolicyRef","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/iam_policy_properties-id"},"type":{"$ref":"#/components/schemas/type"}},"required":["id","type"]},"iam_policy_properties-id":{"type":"string","format":"uuid","description":"ID of the IAM Policy."},"type":{"type":"string","description":"The type of policy, managed indicates it's controlled by the platform.","enum":["managed","organization"]},"iam_action":{"type":"object","title":"Action","properties":{"name":{"type":"string","description":"The name of the action."},"type":{"type":"string","description":"The type that the action belongs to."}},"required":["name","type"]},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"}}},"paths":{"/organizations/{organizationId}/access-keys/{accessKeyId}":{"get":{"description":"Retrieve a single access key.","operationId":"getAccessKey","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessKey"}}},"description":"OK"},"404":{"$ref":"#/components/responses/notFound"}},"summary":"Get access key","tags":["organization_access_key"]}}}}
```

## Delete access key

> Remove the access key from the organization.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization credentials.","name":"organization_access_key"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"}},"schemas":{"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}}}},"paths":{"/organizations/{organizationId}/access-keys/{accessKeyId}":{"delete":{"description":"Remove the access key from the organization.","operationId":"deleteAccessKey","responses":{"204":{"description":"OK"},"404":{"$ref":"#/components/responses/notFound"}},"summary":"Delete access key","tags":["organization_access_key"]}}}}
```

## Update access key

> Update the access key's properties.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization credentials.","name":"organization_access_key"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"UpdateAccessKey":{"type":"object","additionalProperties":false,"title":"UpdateAccessKey","minProperties":1,"properties":{"name":{"$ref":"#/components/schemas/AccessKeyName"},"description":{"$ref":"#/components/schemas/AccessKeyDescription"},"roleIds":{"type":"array","description":"IAM roles attached to this access key.","deprecated":true,"items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":5},"roleRefs":{"type":"array","uniqueItems":true,"description":"The list of IAM roles to assign to the access key.","items":{"$ref":"#/components/schemas/iam_role_ref"},"minItems":1,"maxItems":5}}},"AccessKeyName":{"type":"string","description":"Access key name.","minLength":1,"maxLength":256},"AccessKeyDescription":{"type":"string","description":"Access key description.","minLength":1,"maxLength":256},"iam_role_ref":{"type":"object","title":"RoleReference","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["organization","managed"]},"workspaces":{"nullable":true,"type":"array","items":{"type":"string","format":"uuid"}}},"required":["id","type"]},"AccessKeyListItem":{"type":"object","additionalProperties":false,"title":"AccessKey","description":"The access key record.","properties":{"id":{"type":"string","description":"ID of the access key."},"organizationId":{"type":"string","description":"ID of the organization that owns the access key."},"name":{"$ref":"#/components/schemas/AccessKeyName"},"type":{"$ref":"#/components/schemas/AccessKeyType"},"description":{"$ref":"#/components/schemas/AccessKeyDescription"},"suffix":{"$ref":"#/components/schemas/AccessKeySuffix"},"lastUsedAt":{"type":"string","format":"date-time","description":"When the access key was last used.","nullable":true},"createdAt":{"type":"string","format":"date-time","description":"When the access key was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the access key was last updated."},"roleIds":{"type":"array","uniqueItems":true,"deprecated":true,"description":"IDs of IAM roles attached to the access key.","items":{"type":"string"},"minItems":0,"maxItems":5},"roleRefs":{"type":"array","uniqueItems":true,"description":"The list of IAM roles assigned to the access key.","items":{"$ref":"#/components/schemas/iam_role_ref"},"minItems":0,"maxItems":5}},"required":["id","organizationId","name","suffix","createdAt"]},"AccessKeyType":{"type":"string","enum":["user","workspace","workspace-scim","service","organization"]},"AccessKeySuffix":{"type":"string","description":"Access key suffix.","minLength":6,"maxLength":6},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}},"DetailedError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"},"details":{"type":"object","description":"Detailed information on where the error exists, usually the field name on the request payload","additionalProperties":{"type":"array","description":"The error description for the specific detail","items":{"type":"string"}}}}}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"},"staleObject":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Server had a temporary failure"},"invalidRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedError"}}},"description":"Request validation failed"}}},"paths":{"/organizations/{organizationId}/access-keys/{accessKeyId}":{"patch":{"description":"Update the access key's properties.","operationId":"updateAccessKey","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAccessKey"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessKeyListItem"}}},"description":"OK"},"404":{"$ref":"#/components/responses/notFound"},"409":{"$ref":"#/components/responses/staleObject"},"422":{"$ref":"#/components/responses/invalidRequest"}},"summary":"Update access key","tags":["organization_access_key"]}}}}
```