Quickstart

1. Obtain user authorization

This example reads the current user's profile. Follow Authorization Code + PKCE to obtain a user access token with user:profile:read. A client_credentials service token does not supply user identity. API keys must also satisfy the endpoint's identity and scope requirements; see API keys.

Create an application in Applications, then create a Public or Confidential OAuth client under its Credentials page. Register your callback URI and allowed scopes. Public clients use PKCE and have no client_secret.

2. Select an environment

Environment	OAuth issuer	API base URL
staging	`https://accounts-staging.appforges.com`	`https://api-staging.appforges.com`
production	`https://accounts.appforges.com`	`https://api.appforges.com`

Store the user token in APPFORGES_ACCESS_TOKEN, outside Git, logs and frontend code. Match the issuer to the API environment. These examples default to staging; obtain independent production authorization before selecting the production API.

export APPFORGES_API_BASE_URL=https://api-staging.appforges.com

3. Install an official SDK

Use the command for your language project. SDK package version 0.59.4 and API date version 2026-04-01 are separate values.

npm install @appforges/sdk@0.59.4
python -m pip install appforges==0.59.4
go get github.com/appforges/appforges-sdk-go@v0.59.4

4. Make one read-only call

Save TypeScript as .mts, compile it with TypeScript, then run it with Node. Save Python as .py. Run Go within an initialized module. These first-call examples disable retries to expose a single request; the SDK normally allows two retries.

TypeScript

import { AppForges } from "@appforges/sdk";
import { BearerAuth } from "@appforges/sdk/runtime/auth/bearer";
 
const client = new AppForges({
  baseURL: process.env.APPFORGES_API_BASE_URL || "https://api-staging.appforges.com",
  auth: new BearerAuth(process.env.APPFORGES_ACCESS_TOKEN!),
  retry: { maxRetries: 0 },
});
const profile = await client.users.getProfile({
  headers: { "X-AppForges-Api-Version": "2026-04-01" },
});
console.log(profile.user_id);

Python

import os
from appforges import AppForges, BearerAuth
 
with AppForges(
    base_url=os.environ.get("APPFORGES_API_BASE_URL", "https://api-staging.appforges.com"),
    auth=BearerAuth(os.environ["APPFORGES_ACCESS_TOKEN"]),
    max_retries=0,
) as client:
    profile = client.users.get_profile(
        headers={"X-AppForges-Api-Version": "2026-04-01"},
    )
    print(profile.user_id)

Go

package main
 
import (
    "context"
    "fmt"
    "log"
    "os"
    appforges "github.com/appforges/appforges-sdk-go"
    "github.com/appforges/appforges-sdk-go/runtime"
)
 
func main() {
    base := os.Getenv("APPFORGES_API_BASE_URL")
    if base == "" { base = "https://api-staging.appforges.com" }
    client, err := appforges.NewClient(
        runtime.WithBaseURL(base),
        runtime.WithBearerToken(os.Getenv("APPFORGES_ACCESS_TOKEN")),
        runtime.WithMaxRetries(0),
    )
    if err != nil { log.Fatal(err) }
    defer client.Close()
    profile, err := client.Users.GetProfile(context.Background(),
        runtime.WithHeader("X-AppForges-Api-Version", "2026-04-01"))
    if err != nil { log.Fatal(err) }
    userID, ok := profile.UserId.Get()
    if !ok { log.Fatal("missing user_id") }
    fmt.Println(userID)
}

Wire properties retain snake_case. The response is a flat profile; this is a partial illustrative response:

{ "user_id": "example-user", "phone_number": "example-phone" }

Or use curl:

curl --fail-with-body "${APPFORGES_API_BASE_URL}/v1/users/me" \
  -H "Authorization: Bearer ${APPFORGES_ACCESS_TOKEN}" \
  -H "X-AppForges-Api-Version: 2026-04-01"

5. Inspect the response

Use X-Request-Id and X-Trace-Id for diagnostics, and X-AppForges-Resolved-Api-Version for the resolved version. Rate headers are X-RateLimit-Limit-Short, X-RateLimit-Remaining-Short, X-RateLimit-Reset-Short and their -Long equivalents. Read actual limits from responses. Honor Retry-After on 429; do not generate a burst to test quotas.

For 401 check credentials, issuer and expiry; for 403 check identity and scope. Continue with errors and retries, versioning and SDKs.