Your first API request

1. Create a personal access token

Sign in to your Vigil dashboard and open Account → API tokens at /app/account/tokens. Create a token with a name that identifies your integration. Copy the secret when it is displayed; it cannot be retrieved again.

Keep the token in a server-side environment variable or secret store. Do not put it in browser JavaScript or commit it to source control.

2. Set your environment

Replace the example host below with the host of your Vigil dashboard, without the /app path. example.com is a placeholder, not a Vigil environment.

export VIGIL_ORIGIN="https://example.com"
export VIGIL_TOKEN="your-personal-access-token"

3. Query your identity

curl --fail-with-body "$VIGIL_ORIGIN/api/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $VIGIL_TOKEN" \
  --data '{"query":"query { identity { id fullName } }"}'

A successful response includes your account’s ID and name under data.identity. Always inspect the errors array as well as the HTTP status: a GraphQL request can return HTTP 200 with field errors or partial data.

If identity is null, check that the token is valid, unexpired, and belongs to this environment.

TypeScript example

Run this from your server or a local script with the same environment variables:

const origin = process.env.VIGIL_ORIGIN;
const token = process.env.VIGIL_TOKEN;
if (!origin || !token) throw new Error("Set VIGIL_ORIGIN and VIGIL_TOKEN");

const response = await fetch(new URL("/api/graphql", origin), {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({ query: "query { identity { id fullName } }" }),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const result = await response.json();
if (result.errors?.length) throw new Error(JSON.stringify(result.errors));
if (!result.data?.identity) throw new Error("Token was not authenticated");
console.log(result.data.identity);

Next steps

Read Authentication before deploying an integration. The endpoint supports GraphQL introspection, so a GraphQL client can explore available queries and their argument types.