OpenFGA

Note

Included in the Enterprise plan. On other plans the page is visible but turned off. Contact sales to get access.

OpenFGA is an open source engine for fine-grained authorization: you describe who can do what on which object, and your backend asks OpenFGA whether an action is allowed. Skycloak runs a dedicated OpenFGA instance for you, with its own database, bound to one realm of your cluster. The instance accepts only tokens signed by that realm.

An instance is bound to one realm, chosen when you create it and never changed. Each realm can have one instance, and your workspace has a limit on how many instances it can run. This release has no Keycloak user or group sync and no model editor: you write models and relationship tuples through the OpenFGA API.

Create an instance

1. Open a cluster and choose OpenFGA in the sidebar, under Configure.
2. Select New instance.
3. Pick the realm. Realms that already have an instance are listed last and cannot be picked. To use a realm that does not exist yet, select New realm.
4. Select Create instance.

The instance starts as Provisioning and becomes Ready in a few minutes. The page updates by itself. If it shows Failed, the reason is shown under the status.

When the instance is ready, its page shows three values you copy with Copy:

• API URL: where your backend sends OpenFGA requests.
• Issuer: the realm that signs the tokens OpenFGA accepts.
• Audience: the value a token must carry. It is the same as the API URL.

Add the audience mapper in Keycloak

OpenFGA rejects a token that does not carry the instance’s audience, so add it to the client your backend uses to get tokens.

1. Open the realm in Keycloak and go to Clients, then select your client.
2. Open the Client scopes tab and select the client’s dedicated scope (named after the client, ending in -dedicated).
3. Select Configure a new mapper, then Audience.
4. Give it a name such as openfga.
5. Under Included Custom Audience, paste the Audience value from the instance page.
6. Turn on Add to access token and save.

Get a token and call OpenFGA

Request an access token from the realm with the client credentials grant, then send it as a bearer token to the API URL.

TOKEN=$(curl -s "$ISSUER/protocol/openid-connect/token" \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET" | jq -r .access_token)

curl "$API_URL/stores" \
  -H "Authorization: Bearer $TOKEN"

A request with no token, or with a token from another realm or without the audience, is answered with 401.

To start modelling, create a store and write an authorization model with the OpenFGA API.

Delete an instance

Open the instance and select Delete instance. Type the realm name to confirm. Deleting removes the deployment, its route and its database, and every store, model and tuple in it. This cannot be undone. The instance shows Deleting until everything is gone, then it leaves the list.

Deleting a cluster also deletes the OpenFGA instances bound to its realms. The confirmation names them first. Deleting a realm deletes its instance too.

Without access

If OpenFGA is not available for your workspace, the page explains why and has no New instance button. If you already have instances, for example because access was turned off later, they keep running. You can still open and delete them.

Use the API, Terraform or MCP

Everything on the page is also available outside the dashboard. Your API key needs the openfga:read scope to list and get instances, and openfga:write to create and delete them.

API

curl -X POST "https://api.skycloak.io/clusters/$CLUSTER_ID/openfga-instances" \
  -H "API-Key: $SKYCLOAK_API_KEY" \
  -H "API-Version: 2026-06-01.beta" \
  -H "Content-Type: application/json" \
  -d '{"realm": "my-service"}'

The call returns 202 with the instance in the provisioning state. Poll GET /clusters/{cluster_id}/openfga-instances/{instance_id} until status is ready or failed. A workspace without access gets 403. See the API reference for the list, get and delete operations.

Terraform

resource "skycloak_openfga_instance" "main" {
  cluster_id = skycloak_cluster.main.id
  realm      = "my-service"
}

output "openfga_api_url" {
  value = skycloak_openfga_instance.main.api_url
}

Changing the realm replaces the instance, which deletes its data. Import an existing instance with its ID.

MCP

The Skycloak MCP server has skycloak_list_openfga_instances, skycloak_get_openfga_instance, skycloak_create_openfga_instance and skycloak_delete_openfga_instance. The delete tool needs confirm=true.

Need help?

Ask at support.skycloak.io.