Quickstart

This walks from an empty Gate instance to a backend that reads configuration over HTTP. It takes about ten minutes and uses a service API key, which is the shortest path to a working call. If your product needs to sign users in, read Choose an integration mode first — the credential is different.

Create an account. Open /sign-in and register with email and password (minimum six characters), or use GitHub or Google if the operator configured them.
Create an organization. Go to /dashboard/organizations/new. You become its owner, which grants every control-plane permission.
Create a project. Inside the organization, choose New project. Gate creates the development, staging, and production environments for you, along with two project roles: project-admin (permission *) and member (permission profile:read).
Mint a service API key. Open the project's Credentials tab and create a service account. Give it the scopes it needs — for this walkthrough, config:read. The key is displayed once.
Call the API. Use the key as an X-API-Key header.

Store the key

The key looks like gate_sk_<12 chars>_<43 chars>. Gate stores only an HMAC-SHA256 digest of it, so a lost key cannot be recovered — only replaced. Put it in your own secret store and never commit it.

Your first request

Read every configuration entry in an environment. Replace ENVIRONMENT_ID with the id shown on the project's Config tab.

const response = await fetch(
  `https://evonia-gate.annatarhe.com/api/v1/environments/${environmentId}/configs`,
  {
    headers: {
      "x-api-key": process.env.GATE_API_KEY!,
      "x-request-id": crypto.randomUUID(),
    },
  },
);

if (!response.ok) {
  const problem = await response.json();
  throw new Error(`${problem.title} (request ${problem.requestId})`);
}

const { data } = await response.json();
console.log(data);

curl -sS "https://evonia-gate.annatarhe.com/api/v1/environments/$ENVIRONMENT_ID/configs" \
  -H "x-api-key: $GATE_API_KEY" \
  -H "x-request-id: $(uuidgen)"

req, err := http.NewRequestWithContext(ctx, http.MethodGet,
    fmt.Sprintf("https://evonia-gate.annatarhe.com/api/v1/environments/%s/configs", environmentID), nil)
if err != nil {
    return err
}
req.Header.Set("X-API-Key", os.Getenv("GATE_API_KEY"))
req.Header.Set("X-Request-Id", uuid.NewString())

res, err := http.DefaultClient.Do(req)
if err != nil {
    return err
}
defer res.Body.Close()

var payload struct {
    Data []struct {
        Key    string `json:"key"`
        Kind   string `json:"kind"`
        Value  string `json:"value"`
        Masked bool   `json:"masked"`
    } `json:"data"`
}
return json.NewDecoder(res.Body).Decode(&payload)

var request = URLRequest(
    url: URL(string: "https://evonia-gate.annatarhe.com/api/v1/environments/\(environmentID)/configs")!
)
request.setValue(apiKey, forHTTPHeaderField: "X-API-Key")
request.setValue(UUID().uuidString, forHTTPHeaderField: "X-Request-Id")

let (data, response) = try await URLSession.shared.data(for: request)
guard let http = response as? HTTPURLResponse, http.statusCode == 200 else {
    throw GateError.requestFailed
}
let payload = try JSONDecoder().decode(ConfigListResponse.self, from: data)

Every successful response wraps its payload in a data key:

JSON

{
  "data": [
    { "key": "FEATURE_FLAGS", "kind": "variable", "value": "beta", "masked": false },
    { "key": "SESSION_SIGNING_KEY", "kind": "secret", "value": null, "masked": true }
  ]
}

Secrets are masked in list responses regardless of who is asking. To read one, request it by key — see Configuration and secrets.

When it does not work

Status	Meaning	Usual cause
`401`	Authentication required	The key is malformed, revoked, expired, or its service account is disabled. Gate does not distinguish between these.
`403`	Permission denied	The key is valid but lacks the scope, or is pinned to a different environment.
`404`	Not found	The environment id is wrong, or it belongs to a project the key cannot see.

Every response carries an x-request-id header — the one you sent, or one Gate generated. Quote it when reporting a problem. The full list is in the error catalog.

Decide which credential your actual product needs. A service key is right for a backend that administers Gate; it is the wrong tool for signing users in.

Quickstart#

Store the key#

Your first request#

When it does not work#

Next#

Quickstart

Store the key

Your first request

When it does not work

Next