> ## Documentation Index
> Fetch the complete documentation index at: https://trophy-ci-i18n-auto-translations.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate with the Application API using user-scoped application API keys transmitted in the `X-API-KEY` header.

<h2 id="api-key-types">
  API key types
</h2>

The Application API accepts two types of API keys:

| Key type                                      | Scope          | Where to use                  | Safe client-side? |
| --------------------------------------------- | -------------- | ----------------------------- | ----------------- |
| [Application API keys](#application-api-keys) | Single user    | Application API only          | Yes               |
| [Admin API keys](/admin-api/authentication)   | Entire account | Application API and Admin API | No                |

Use application API keys when you want end users or client apps to call the Application API with permissions limited to one user. Use [admin API keys](/admin-api/authentication) for trusted server-side integrations that need broad access.

<h2 id="application-api-keys">
  Application API keys
</h2>

Application API keys are scoped to a specific user. Each key can only perform Application API operations on behalf of the user it was created for, which makes them safe to expose in client-side environments.

Application API keys cannot be used with the Admin API.

<h3 id="creating-application-api-keys">
  Creating application API keys
</h3>

Create application API keys with the [Admin API](/admin-api/endpoints/application-api-keys/create-application-api-keys). You authenticate that request with an [admin API key](/admin-api/authentication).

You can create keys for up to 100 users per request. The full key value is returned once at creation time and cannot be retrieved again—store it securely or deliver it to the client immediately.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://admin.trophy.so/v1/application-api-keys \
       -H "X-API-KEY: <api-key>" \
       -H "Content-Type: application/json" \
       -d '[
         { "userId": "user_123" },
         { "userId": "user_456" }
       ]'
  ```

  ```typescript Node theme={null}
  await trophy.admin.applicationApiKeys.create([
    { userId: "user_123" },
    { userId: "user_456" },
  ]);
  ```

  ```python Python theme={null}
  client.admin.application_api_keys.create(
      request=[
          CreateApplicationKeyRequestItem(
              user_id="user_123",
          ),
          CreateApplicationKeyRequestItem(
              user_id="user_456",
          ),
      ],
  )
  ```

  ```php PHP theme={null}
  $trophy->admin->applicationApiKeys->create([
      ['userId' => 'user_123'],
      ['userId' => 'user_456'],
  ]);
  ```

  ```java Java theme={null}
  CreateApplicationKeysResponse response = client.admin().applicationApiKeys().create(
    List.of(
      CreateApplicationKeyRequestItem.builder().userId("user_123").build(),
      CreateApplicationKeyRequestItem.builder().userId("user_456").build()
    )
  );
  ```

  ```go Go theme={null}
  response, err := client.Admin.ApplicationApiKeys.Create(
      context.TODO(),
      []*api.CreateApplicationKeyRequestItem{
          {UserId: "user_123"},
          {UserId: "user_456"},
      },
  )
  ```

  ```csharp C# theme={null}
  await trophy.Admin.ApplicationApiKeys.CreateAsync(new[]
  {
      new CreateApplicationKeyRequestItem { UserId = "user_123" },
      new CreateApplicationKeyRequestItem { UserId = "user_456" },
  });
  ```

  ```ruby Ruby theme={null}
  result = client.admin.application_api_keys.create([
    { user_id: 'user_123' },
    { user_id: 'user_456' }
  ])
  ```
</CodeGroup>

A successful response includes the key ID (used later to delete the key), the user ID, the full key, and a readable prefix:

```json theme={null}
{
  "created": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "user_123",
      "key": "app_XXXXX.YOUR_API_KEY",
      "prefix": "app_XXXXX"
    }
  ],
  "issues": []
}
```

<h3 id="anatomy-of-an-application-api-key">
  Anatomy of an application API key
</h3>

Each application API key is made up of 2 parts separated by a period:

```bash theme={null}
{prefix}.{body}
```

* The *prefix* identifies the key (for example `app_XXXXX`) and is safe to log or display.
* The *body* is the secret part, and is only shown once when you create the key.

<Note>
  When using the API, both parts of your application API key must be sent in the
  `X-API-KEY` header.
</Note>

<h3 id="authenticating-requests">
  Authenticating requests
</h3>

Include the full application API key in the `X-API-KEY` header on Application API requests, or pass it when initializing an SDK client. The key only authorizes operations for the user it is scoped to—requests for other users return an error.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.trophy.so/v1/users/user_123/metrics/<key> \
       -H "X-API-KEY: YOUR_API_KEY"
  ```

  ```typescript Node theme={null}
  import { TrophyApiClient } from "@trophyso/node";

  const trophy = new TrophyApiClient({
    apiKey: "YOUR_API_KEY",
  });
  ```

  ```python Python theme={null}
  from trophy import TrophyApi

  client = TrophyApi(
      api_key="YOUR_API_KEY",
  )
  ```

  ```php PHP theme={null}
  use Trophy\TrophyClient;

  $trophy = new TrophyClient("YOUR_API_KEY");
  ```

  ```java Java theme={null}
  TrophyApiClient client = TrophyApiClient.builder()
      .apiKey("YOUR_API_KEY")
      .build();
  ```

  ```go Go theme={null}
  import (
    trophyclient "github.com/trophyso/trophy-go/client"
    "github.com/trophyso/trophy-go/option"
  )

  client := trophyclient.NewClient(
    option.WithApiKey("YOUR_API_KEY"),
  )
  ```

  ```csharp C# theme={null}
  var trophy = new TrophyApiClient(
      apiKey: "YOUR_API_KEY"
  );
  ```

  ```ruby Ruby theme={null}
  client = Trophy::Client.new(
    api_key: "YOUR_API_KEY"
  )
  ```
</CodeGroup>

If you do not pass an API key, or your API key is invalid, you'll receive a `401` response code.

<h3 id="deleting-application-api-keys">
  Deleting application API keys
</h3>

Delete application API keys by ID with the [Admin API](/admin-api/endpoints/application-api-keys/delete-application-api-keys). Use the UUID returned when the key was created.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://admin.trophy.so/v1/application-api-keys?ids=550e8400-e29b-41d4-a716-446655440000" \
       -H "X-API-KEY: <api-key>"
  ```

  ```typescript Node theme={null}
  await trophy.admin.applicationApiKeys.delete({
    ids: ["550e8400-e29b-41d4-a716-446655440000"],
  });
  ```

  ```python Python theme={null}
  client.admin.application_api_keys.delete(
      ids=["550e8400-e29b-41d4-a716-446655440000"],
  )
  ```

  ```php PHP theme={null}
  $trophy->admin->applicationApiKeys->delete([
      'ids' => ['550e8400-e29b-41d4-a716-446655440000'],
  ]);
  ```

  ```java Java theme={null}
  DeleteApplicationKeysResponse response = client.admin().applicationApiKeys().delete(
    ApplicationApiKeysDeleteRequest.builder()
      .ids(List.of("550e8400-e29b-41d4-a716-446655440000"))
      .build()
  );
  ```

  ```go Go theme={null}
  response, err := client.Admin.ApplicationApiKeys.Delete(
      context.TODO(),
      &admin.ApplicationApiKeysDeleteRequest{
          Ids: []*string{
              api.String("550e8400-e29b-41d4-a716-446655440000"),
          },
      },
  )
  ```

  ```csharp C# theme={null}
  await trophy.Admin.ApplicationApiKeys.DeleteAsync(new ApplicationApiKeysDeleteRequest
  {
      Ids = new[] { "550e8400-e29b-41d4-a716-446655440000" },
  });
  ```

  ```ruby Ruby theme={null}
  result = client.admin.application_api_keys.delete(
    ids: ['550e8400-e29b-41d4-a716-446655440000']
  )
  ```
</CodeGroup>

<Error>Once API keys are deleted, they cannot be recovered.</Error>

<h2 id="get-support">
  Get Support
</h2>

Want to get in touch with the Trophy team? Reach out to us via [email](mailto:support@trophy.so). We're here to help!