Getting started

Before the first request

1. A CYJ administrator creates/configures an API client and selects its scopes.
2. The administrator normally maps the client to an active worker resource with assigned tasks. An identity-only client can authenticate but has no task ownership.
3. The administrator issues a credential. Copy the secret when displayed once and place it in server-side secret storage. There is no public self-service registration.
4. Use your installation’s HTTPS origin. Plain HTTP is for local Development only.

1. Confirm the identity #

Load CYJ_API_TOKEN from your secret store. The assignment below is an intentionally invalid placeholder for this fictional example.

curl · shell environment

export CYJ_API_TOKEN='EXAMPLE_TOKEN_NOT_VALID'

Call GET /api/v1/identity with the credential header:

curl · identity request

curl -i 'https://cyj.example/api/v1/identity' \
  -H "Authorization: Bearer $CYJ_API_TOKEN"

A successful resource-mapped client receives:

{
  "clientId": 12,
  "clientName": "Atlas worker",
  "organisation": {
    "id": 10,
    "name": "Northstar Studio"
  },
  "resource": {
    "id": 7,
    "name": "Atlas"
  },
  "scopes": [
    "tasks:read",
    "tasks:update",
    "tasks:notes"
  ]
}

The response names the authenticated client, organisation, resource and granted scopes. A null resource means identity-only access. A 401 requires checking the credential and its administrator-managed state; a successful identity read does not grant unassigned work.

2. Discover assigned work

curl -i 'https://cyj.example/api/v1/tasks/available' \
  -H "Authorization: Bearer $CYJ_API_TOKEN"

The response is a task array. [] is a successful empty result: no eligible owned task is being offered now. Available means scheduler-runnable, unblocked and without a live claim. It is not a general “Ready status” filter. Read discovering tasks before selecting work.

The same first steps in C#

This is a .NET HttpClient example, not an SDK. It runs in your server/worker environment and prints the fictional identity/task response for inspection; avoid logging sensitive business responses in production.

using System.Net.Http.Headers;

using var http = new HttpClient { BaseAddress = new Uri("https://cyj.example/") };
var credential = Environment.GetEnvironmentVariable("CYJ_API_TOKEN")
    ?? throw new InvalidOperationException("Load CYJ_API_TOKEN from your secret store.");
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", credential);

using var identity = await http.GetAsync("api/v1/identity");
identity.EnsureSuccessStatusCode();
Console.WriteLine(await identity.Content.ReadAsStringAsync());
using var available = await http.GetAsync("api/v1/tasks/available");
available.EnsureSuccessStatusCode();
Console.WriteLine(await available.Content.ReadAsStringAsync());

Next: inspect, then claim

Use tasks:read to inspect GET /api/v1/tasks/42, retain its ETag, and follow worker claims before active work. Use authentication for rotation and resource mapping, scopes for least privilege and errors when a request fails.