# Team API Keys

### Overview

Team API keys are designed for service accounts that manage Open Authorization API (OAA) integrations assigned to a team. Similar to personal API keys, these keys authenticate API requests, and can be revoked or reinstated to control programmatic access to Veza. Each key is associated with a single team and has the `oaa_push` role, restricted to specific read and write operations for creating and updating OAA data sources.

Team API keys are limited to the following operations:

* [Create Custom Provider Data Source](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/oaa/rest-api/operations#create-custom-provider)
* [Push Custom Provider Data Source](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/oaa/rest-api/operations#create-custom-provider-datasource)
* [Delete Custom Provider Data Source](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/oaa/rest-api/operations#delete-custom-provider-datasource)
* [Get Custom Provider Data Source](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/oaa/rest-api/operations#get-datasource-by-id)
* [List Custom Provider Templates](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/oaa/rest-api)
* [List Custom Providers](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/oaa/rest-api/operations#list-custom-providers)
* [List Custom Provider Data Sources](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/oaa/rest-api/operations#list-custom-provider-datasources)
* [Push Custom Provider CSV Data Source](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/oaa/rest-api/operations#push-custom-provider-datasource-csv)
* [Get User](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/users-teams/..#get-user)

Administrators can create and manage team API keys using the endpoints documented below. Note that Team API Keys are currently provided as an early access feature, and `/preview/` API operations are subject to change as capabilities are added or modified.

### List Team API Keys

**Method:** GET **Endpoint:** `/api/preview/teamkeys`

Returns API key details such as last activity time and status. If the query includes a `team_id` filter expression, only keys for that team are listed.

Note: When using a personal API key for a [non-root team](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/authentication#team-api-keys-early-access), the `team_id` filter is automatically applied. Only root team administrators can view keys across all teams.

{% openapi src="<https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-78f548f68894fbfb26b0fd9627c7e562be046dfa%2Fopenapi.yaml?alt=media>" path="/api/preview/teamkeys" method="get" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-78f548f68894fbfb26b0fd9627c7e562be046dfa%2Fopenapi.yaml?alt=media)
{% endopenapi %}

**Example Request:**

```shell
curl -X GET "https://<base-url>/api/preview/teamkeys?filter=team_id+eq+%2260437fa0-15ab-4c1f-a211-010543ac8a89%22" \
 -H "accept: application/json"
```

**Example Response:**

```json
{
  "values": [
    {
      "id": "54807783-c5ec-4efd-9d1b-853bada658dd",
      "access_key": "",
      "name": "AWS Team Key",
      "created_at": "2024-06-25T08:30:17.087351612Z",
      "last_access_at": "2024-06-25T08:30:17.087351612Z",
      "status": "ACTIVE",
      "team_id": "60437fa0-15ab-4c1f-a211-010543ac8a89"
    }
  ],
  "next_page_token": ""
}
```

### Create Team API Key

**Method:** POST **Endpoint:** `/api/preview/teamkeys`

Create an API key by providing a key `name` and team `team_id`. The response includes the `access_key`, which cannot be retrieved again.

{% openapi src="<https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-78f548f68894fbfb26b0fd9627c7e562be046dfa%2Fopenapi.yaml?alt=media>" path="/api/preview/teamkeys" method="post" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-78f548f68894fbfb26b0fd9627c7e562be046dfa%2Fopenapi.yaml?alt=media)
{% endopenapi %}

**Example Request:**

```shell
curl -X POST "https://<base-url>/api/preview/teamkeys" \
 -H "accept: application/json" \
 -H "content-type: application/json" \
 -d '{"name":"New Team API Key","team_id":"60437fa0-15ab-4c1f-a211-010543ac8a89"}'
```

**Example Response:**

```json
{
  "value": {
    "id": "7ddd5e0c-29cd-41c5-b41f-884b2d24b05d",
    "access_key": "<access key>",
    "name": "New Team API Key",
    "created_at": "2024-08-26T21:29:59.409761363Z",
    "last_access_at": "2024-08-26T21:29:59.409761363Z",
    "status": "ACTIVE",
    "team_id": "60437fa0-15ab-4c1f-a211-010543ac8a89"
  }
}
```

### Remove Team API Key

**Method:** DELETE **Endpoint:** `/api/preview/teamkeys/{id}`

Permanently delete a team API key.

{% openapi src="<https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-78f548f68894fbfb26b0fd9627c7e562be046dfa%2Fopenapi.yaml?alt=media>" path="/api/preview/teamkeys/{id}" method="delete" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-78f548f68894fbfb26b0fd9627c7e562be046dfa%2Fopenapi.yaml?alt=media)
{% endopenapi %}

**Example Request:**

```shell
curl -X DELETE "https://<base-url>/api/preview/teamkeys/7ddd5e0c-29cd-41c5-b41f-884b2d24b05d" \
 -H "accept: application/json"
```

**Example Response:**

```json
{
  "value": {
    "id": "7ddd5e0c-29cd-41c5-b41f-884b2d24b05d",
    "access_key": "",
    "name": "Updated API Key",
    "created_at": "2024-08-26T21:29:59.409761363Z",
    "last_access_at": "2024-08-26T21:29:59.409761363Z",
    "status": "INACTIVE",
    "team_id": "60437fa0-15ab-4c1f-a211-010543ac8a89"
  }
}
```

### Revoke Team API Key

**Method:** POST **Endpoint:** `/api/preview/teamkeys/{id}:revoke`

Suspend usage of a team API key, changing the status to `INACTIVE`.

{% openapi src="<https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-78f548f68894fbfb26b0fd9627c7e562be046dfa%2Fopenapi.yaml?alt=media>" path="/api/preview/teamkeys/{id}:revoke" method="post" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-78f548f68894fbfb26b0fd9627c7e562be046dfa%2Fopenapi.yaml?alt=media)
{% endopenapi %}

**Example Request:**

```shell
curl -X POST "https://<base-url>/api/preview/teamkeys/7ddd5e0c-29cd-41c5-b41f-884b2d24b05d:revoke" \
 -H "accept: application/json"
```

**Example Response:**

```json
{}
```

### Reinstate Team API Key

**Method:** POST **Endpoint:** `/api/preview/teamkeys/{id}:reinstate`

Reinstates a previously revoked team API key, changing the status to `ACTIVE`.

{% openapi src="<https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-78f548f68894fbfb26b0fd9627c7e562be046dfa%2Fopenapi.yaml?alt=media>" path="/api/preview/teamkeys/{id}:reinstate" method="post" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-78f548f68894fbfb26b0fd9627c7e562be046dfa%2Fopenapi.yaml?alt=media)
{% endopenapi %}

**Example Request:**

```shell
curl -X POST "https://<base-url>/api/preview/teamkeys/7ddd5e0c-29cd-41c5-b41f-884b2d24b05d:reinstate" \
 -H "accept: application/json"
```

**Example Response:**

```json
{}
```

### Update Team API Key

**Method:** PATCH **Endpoint:** `/api/preview/teamkeys/{value.id}`

Use this operation to update the display name of a team API key.

{% openapi src="<https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-78f548f68894fbfb26b0fd9627c7e562be046dfa%2Fopenapi.yaml?alt=media>" path="/api/preview/teamkeys/{value.id}" method="patch" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-78f548f68894fbfb26b0fd9627c7e562be046dfa%2Fopenapi.yaml?alt=media)
{% endopenapi %}

**Example Request:**

```shell
curl -X PATCH "https://<base-url>/api/preview/teamkeys/7ddd5e0c-29cd-41c5-b41f-884b2d24b05d" \
 -H "accept: application/json"\
 -H "content-type: application/json" \
 -d '{"name":"Updated API Key"}'
```

**Example Response:**

```json
{
  "value": {
    "id": "7ddd5e0c-29cd-41c5-b41f-884b2d24b05d",
    "access_key": "",
    "name": "Updated API Key",
    "created_at": "2024-08-26T21:29:59.409761363Z",
    "last_access_at": "2024-08-26T21:29:59.409761363Z",
    "status": "ACTIVE",
    "team_id": "60437fa0-15ab-4c1f-a211-010543ac8a89"
  }
}
```