Authentication

API key types

The Application API accepts two types of API keys:

Key type	Scope	Where to use	Safe client-side?
Application API keys	Single user	Application API only	Yes
Admin API keys	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 for trusted server-side integrations that need broad access.

Application API keys

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.

Creating application API keys

Create application API keys with the Admin API. You authenticate that request with an admin API key. 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.

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" }
     ]'

await trophy.admin.applicationApiKeys.create([
  { userId: "user_123" },
  { userId: "user_456" },
]);

client.admin.application_api_keys.create(
    request=[
        CreateApplicationKeyRequestItem(
            user_id="user_123",
        ),
        CreateApplicationKeyRequestItem(
            user_id="user_456",
        ),
    ],
)

$trophy->admin->applicationApiKeys->create([
    ['userId' => 'user_123'],
    ['userId' => 'user_456'],
]);

CreateApplicationKeysResponse response = client.admin().applicationApiKeys().create(
  List.of(
    CreateApplicationKeyRequestItem.builder().userId("user_123").build(),
    CreateApplicationKeyRequestItem.builder().userId("user_456").build()
  )
);

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

await trophy.Admin.ApplicationApiKeys.CreateAsync(new[]
{
    new CreateApplicationKeyRequestItem { UserId = "user_123" },
    new CreateApplicationKeyRequestItem { UserId = "user_456" },
});

result = client.admin.application_api_keys.create([
  { user_id: 'user_123' },
  { user_id: 'user_456' }
])

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

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

Anatomy of an application API key

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

{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.

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

Authenticating requests

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.

curl https://api.trophy.so/v1/users/user_123/metrics/<key> \
     -H "X-API-KEY: YOUR_API_KEY"

import { TrophyApiClient } from "@trophyso/node";

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

from trophy import TrophyApi

client = TrophyApi(
    api_key="YOUR_API_KEY",
)

use Trophy\TrophyClient;

$trophy = new TrophyClient("YOUR_API_KEY");

TrophyApiClient client = TrophyApiClient.builder()
    .apiKey("YOUR_API_KEY")
    .build();

import (
  trophyclient "github.com/trophyso/trophy-go/client"
  "github.com/trophyso/trophy-go/option"
)

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

var trophy = new TrophyApiClient(
    apiKey: "YOUR_API_KEY"
);

client = Trophy::Client.new(
  api_key: "YOUR_API_KEY"
)

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

Deleting application API keys

Delete application API keys by ID with the Admin API. Use the UUID returned when the key was created.

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

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

client.admin.application_api_keys.delete(
    ids=["550e8400-e29b-41d4-a716-446655440000"],
)

$trophy->admin->applicationApiKeys->delete([
    'ids' => ['550e8400-e29b-41d4-a716-446655440000'],
]);

DeleteApplicationKeysResponse response = client.admin().applicationApiKeys().delete(
  ApplicationApiKeysDeleteRequest.builder()
    .ids(List.of("550e8400-e29b-41d4-a716-446655440000"))
    .build()
);

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

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

result = client.admin.application_api_keys.delete(
  ids: ['550e8400-e29b-41d4-a716-446655440000']
)

Get Support

Want to get in touch with the Trophy team? Reach out to us via email. We’re here to help!

Overview

Achievements

Streaks

Metrics

Points

Leaderboards

Users

API key types

Application API keys

Creating application API keys

Anatomy of an application API key

Authenticating requests

Deleting application API keys

Get Support

​API key types

​Application API keys

​Creating application API keys

​Anatomy of an application API key

​Authenticating requests

​Deleting application API keys

​Get Support

API key types

Application API keys

Creating application API keys

Anatomy of an application API key

Authenticating requests

Deleting application API keys

Get Support