Docs

Integrate in an afternoon

Standard OpenID Connect and OAuth 2.1. Anything that speaks the protocol works; the snippets below use curl so they translate to any stack.

Quick start

Endpoints for this deployment. Everything else is in the discovery document.

  • https://iam-test.extremegym.com.mx/.well-known/openid-configuration discovery
  • https://iam-test.extremegym.com.mx/.well-known/jwks.json signing keys
  • https://iam-test.extremegym.com.mx/connect/authorize · https://iam-test.extremegym.com.mx/connect/token · https://iam-test.extremegym.com.mx/connect/userinfo · https://iam-test.extremegym.com.mx/connect/device
  • https://iam-test.extremegym.com.mx/api/v1 Management API (bearer token, audience https://iam.itfortal.com/api)
  • https://iam-test.extremegym.com.mx/scalar interactive reference

Register a client in the portal (Applications → Register a client) in the environment selected at the top: development to start, production once you ship. Public clients get no secret and must use PKCE; confidential and machine clients get up to two secrets, shown once.

Authorization code with PKCE

For anything with a user in front of it: web apps, SPAs, mobile. Generate a random code_verifier, send its SHA-256 as the challenge, exchange the code with the verifier.

1 · redirect the browser
https://iam-test.extremegym.com.mx/connect/authorize
  ?client_id=my-web-app
  &response_type=code
  &redirect_uri=https://app.example.com/signin-oidc
  &scope=openid%20profile%20email%20offline_access
  &state=af0ifjsldkj
  &nonce=n-0S6_WzA2Mj
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &organization=acme            # optional: pick the organization up front
2 · exchange the code
curl -X POST https://iam-test.extremegym.com.mx/connect/token \
  -d grant_type=authorization_code \
  -d client_id=my-web-app \
  -d client_secret=… \                     # confidential clients only
  -d code=SplxlOBeZQQYbYS6WxSbIA \
  -d redirect_uri=https://app.example.com/signin-oidc \
  -d code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Refresh tokens are single use. Store the new one from every refresh response; replaying an old one revokes the whole chain and the user must sign in again.

Client credentials

For services calling an API without a user. The client's roles come from assignments made to the client itself; the token carries client_id and sub = the client's id.

token request
curl -X POST https://iam-test.extremegym.com.mx/connect/token \
  -d grant_type=client_credentials \
  -d client_id=billing-worker \
  -d client_secret=… \
  -d scope=organizations:read \
  -d resource=https://iam.itfortal.com/api      # the audience you will call
decoded access token (organization application)
{
  "iss": "https://iam-test.extremegym.com.mx/",
  "aud": "https://api.acme.example",
  "sub": "cli_…",
  "client_id": "billing-worker",
  "org_id": "org_…",
  "env": "production",           # the environment slug
  "env_id": "env_…",
  "scope": "invoices:read"
}

Resource servers validate the JWT against the JWKS and check aud, iss (https://iam-test.extremegym.com.mx/), expiry and scope, and for your own APIs also env: the same audience can be registered in several environments, so aud alone does not tell a test token from a production one. The IFConsole internal API reads scope as access:{slug} or access:*.

Device flow

For CLIs, TVs and anything without a browser. The device shows a code; the person enters it at https://iam-test.extremegym.com.mx/device.

1 · request a device code
curl -X POST https://iam-test.extremegym.com.mx/connect/device \
  -d client_id=my-cli \
  -d scope=openid%20profile%20offline_access

{ "device_code": "…", "user_code": "KM7P-3XRT",
  "verification_uri": "https://iam-test.extremegym.com.mx/device",
  "verification_uri_complete": "https://iam-test.extremegym.com.mx/device?user_code=KM7P3XRT",
  "expires_in": 900, "interval": 5 }
2 · poll for the token
curl -X POST https://iam-test.extremegym.com.mx/connect/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
  -d client_id=my-cli \
  -d device_code=…
# 400 authorization_pending → wait `interval` seconds and retry
# 400 slow_down → add 5 seconds to the interval

Token claims

  • sub user id (usr_…) or client id (cli_…); email, email_verified, name per the requested scopes.
  • org_id, org_name when an organization is selected; roles the effective role names in that context.
  • env (environment slug) and env_id for applications registered by an organization; absent for the platform's own applications.
  • permissions (access token only, clients that opt in) the flattened permission list, capped at 4 KB with permissions_truncated: true when cut.
  • amr includes pwd and, after MFA, otp; sid ties the token to the browser session.

Organizations

Pass organization=<slug or org_id> on the authorize request to select one. Without it the IAM uses a verified e-mail domain, then the remembered choice, then shows a picker. Clients flagged "require organization" never issue a token without one.

An application registered by an organization always runs in that organization: a different organization parameter is refused with invalid_request.

Environments

Each organization separates its applications, API resources, secrets and consents into environments. Every organization starts with development; production is created explicitly, once, and can never be deleted or converted from another environment. Members, roles and policies are shared by every environment; a role can also be assigned to a single environment.

  • Non-production accepts http://localhost, loopback (any port) and http on dotless hosts as redirect URIs, and issues shorter-lived tokens (at most 1 hour access, 8 hours refresh by default).
  • Production requires https for every redirect URI and is gated by an activation checklist: at least one application, https-only redirects, an unexpired secret on every confidential or machine application, and an org-admin with confirmed MFA. Until it is activated, its applications receive invalid_client with environment not activated.
  • Tokens carry env and env_id. Validate env alongside aud in production APIs.
  • How many non-production environments you can have, and whether production is available, depends on your plan (iam.environments, iam.environments.production).

Manage them in the portal (Environments) or through https://iam-test.extremegym.com.mx/api/v1/organizations/{orgId}/environments.

Policy documents

version iam-2026-09
{
  "Version": "iam-2026-09",
  "Statement": [
    { "Sid": "ReadOnly", "Effect": "Allow",
      "Action": ["users:read", "organizations:read"], "Resource": "*" },
    { "Sid": "OwnOrgSubscriptions", "Effect": "Allow",
      "Action": "subscriptions:read",
      "Resource": "idr:console:${iam:OrgId}:*:subscription/*" },
    { "Sid": "RequireMfaForDeletes", "Effect": "Deny",
      "Action": "*:delete", "Resource": "*",
      "Condition": { "Bool": { "iam:MfaPresent": "false" } } }
  ]
}

Actions are permission names with * wildcards per segment. Resources are IDRs, idr:{service}:{org}:{env}:{type}/{id}, or patterns over them: any segment may be *, ids take * globs and the variables ${iam:OrgId}, ${iam:UserId}, ${iam:ClientId}, and a final * id covers nested resources. Every API representation exposes its own IDR as idr. Conditions: StringEquals, StringLike, IpAddress, Bool, DateGreaterThan, DateLessThan over iam:OrgId, iam:UserId, iam:ClientId, iam:SourceIp, iam:MfaPresent, iam:CurrentTime, iam:RequestTag/* and the resource-derived iam:ResourceService, iam:ResourceOrg, iam:ResourceEnv, iam:ResourceType. Explicit Deny beats Allow; anything unmatched is denied. The evaluate endpoint takes the concrete IDR of the object being acted on. The JSON schema is published at https://iam-test.extremegym.com.mx/docs/policy-schema.json.

Errors and paging

Every error is an RFC 9457 problem document with a stable code such as organization.slug_taken or entitlement.limit_reached, plus errors per field where relevant. A 402 carries entitlement with the feature, current count, limit and an upgrade URL. Lists return { items, next }; pass next as after to continue. Writes accept an Idempotency-Key header.

API reference

The complete Management API, with every endpoint's required permission, is documented interactively with Scalar: https://iam-test.extremegym.com.mx/scalar. The OpenAPI 3.1 document is at https://iam-test.extremegym.com.mx/openapi/v1.json.