# Call the API

Create a service account and an API key, then make your first request to kosem's API with curl.

In this tutorial, you give a script an identity of its own on kosem, a service account, and call the API with its key. It takes about 5 minutes.

## Before you start [#before-you-start]

You need:

- A project that you're an Owner of. The [Quickstart](/get-started/quickstart) creates one.
- `curl`, in a terminal.

## 1. Create a service account [#1-create-a-service-account]

A service account is an identity for software. Its roles decide what its API keys can do.

1. In your project, click **Settings**, and then **Service accounts**.
2. Click **New service account**.
3. Enter a name, such as `Docs tutorial`. kosem fills in the **Account ID** from it.
4. Under **Role in this project**, select **Viewer**.
5. Click **Create service account**.

## 2. Create an API key [#2-create-an-api-key]

1. On the service account's page, click **Create API key**, and then **Create API key** in the dialog.
2. Copy the key, which starts with `kosem_sk_`. kosem shows it only once.
3. Click **I copied the key**.

Anyone with the key can act as the service account, so keep it out of source code. Keys expire after 90 days by default.

In your terminal, keep the key in a variable:

```sh
export KOSEM_API_KEY='kosem_sk_…'
```

## 3. Find your project's ID [#3-find-your-projects-id]

1. Click **Settings**, and then **General**.
2. Copy the project's **ID**, such as `prj_01m5r9dh9mf0ps98ktkap3562c`.

```sh
export KOSEM_PROJECT='prj_01m5r9dh9mf0ps98ktkap3562c'
```

## 4. Get your project [#4-get-your-project]

```sh
curl -s "https://api.kosem.ai/v1/projects/$KOSEM_PROJECT" \
  -H "Authorization: Bearer $KOSEM_API_KEY"
```

kosem answers with the project:

```json
{
  "name": "projects/prj_01m5r9dh9mf0ps98ktkap3562c",
  "parent": "organizations/org_01m5r8w2k3e9vbt6g0d4x7qz1h",
  "slug": "playground",
  "displayName": "Playground",
  "state": "ACTIVE",
  "createTime": "2026-11-12T09:30:00Z",
  "updateTime": "2026-11-12T09:30:00Z"
}
```

## 5. Try something the key can't do [#5-try-something-the-key-cant-do]

The service account is a Viewer, so it can read the project but not change it. Try to rename the project:

```sh
curl -s -X PATCH "https://api.kosem.ai/v1/projects/$KOSEM_PROJECT" \
  -H "Authorization: Bearer $KOSEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Renamed"}'
```

kosem refuses with a `403` and a problem document that says why:

```json
{
  "status": 403,
  "code": "permission_denied",
  "detail": "…"
}
```

Every error has this shape. [API conventions](/reference/api-conventions#errors) lists the codes and how to tell failures apart.

## 6. Clean up [#6-clean-up]

On the service account's page, click **Delete**, and then **Delete service account**. Its keys stop working at once.

## What you did [#what-you-did]

- Created a service account with the Viewer role on your project.
- Called the API with its key, and saw what a refusal looks like.

## Next steps [#next-steps]

- Read the [API conventions](/reference/api-conventions): resource names, pages and errors.
- Browse the [API reference](/reference/api).
- Learn how [roles and service accounts](/concepts/identity-and-access) work.
