Client Grants

Client Grants define the scopes that a machine-to-machine (M2M) application can request when calling an API. Use this API to manage which APIs your M2M applications can access and what permissions they have.

List Client Grants

Retrieves a list of client grants with their associated scopes.

func (c *Client) List(
    ctx context.Context,
    request *management.ListClientGrantsRequestParameters,
    opts ...option.RequestOption,
) (*core.Page[*string, *management.ClientGrantResponseContent, *management.ListClientGrantPaginatedResponseContent], error)

ctx

context.Context

required

Context for the request

request

*management.ListClientGrantsRequestParameters

Query parameters:

Audience - Filter by API audience
ClientID - Filter by client ID
AllowAnyOrganization - Filter by organization usage
Take - Number of results to retrieve (default: 50)
From - Cursor for pagination

opts

...option.RequestOption

Optional request options

Example

import (
    "context"
    "fmt"
    "log"

    "github.com/auth0/go-auth0/v2/management"
)

params := &management.ListClientGrantsRequestParameters{
    ClientID: management.String("abc123xyz"),
    Take: management.Int(50),
}

page, err := client.Management.ClientGrants.List(context.TODO(), params)
if err != nil {
    log.Fatalf("Failed to list client grants: %v", err)
}

for _, grant := range page.Results {
    fmt.Printf("Grant ID: %s\n", grant.GetID())
    fmt.Printf("Audience: %s\n", grant.GetAudience())
    fmt.Printf("Scopes: %v\n", grant.Scope)
}

Get Client Grant

Retrieves a single client grant by ID.

func (c *Client) Get(
    ctx context.Context,
    id string,
    opts ...option.RequestOption,
) (*management.GetClientGrantResponseContent, error)

ctx

context.Context

required

Context for the request

string

required

The ID of the client grant to retrieve

opts

...option.RequestOption

Optional request options

grant

*management.GetClientGrantResponseContent

Returns the client grant with properties:

ID - Grant identifier
ClientID - Client ID
Audience - API audience (identifier)
Scope - Array of allowed scopes
OrganizationUsage - How organizations may be used
AllowAnyOrganization - Whether any organization can be used

Example

grant, err := client.Management.ClientGrants.Get(
    context.TODO(),
    "cgr_1234567890",
)
if err != nil {
    log.Fatalf("Failed to get client grant: %v", err)
}

fmt.Printf("Client: %s\n", grant.GetClientID())
fmt.Printf("API: %s\n", grant.GetAudience())

Create Client Grant

Creates a new client grant for machine-to-machine authentication.

func (c *Client) Create(
    ctx context.Context,
    request *management.CreateClientGrantRequestContent,
    opts ...option.RequestOption,
) (*management.CreateClientGrantResponseContent, error)

ctx

context.Context

required

Context for the request

request

*management.CreateClientGrantRequestContent

required

The grant configuration:

ClientID - Client ID (required)
Audience - API audience/identifier (required)
Scope - Array of scopes to grant (required)
OrganizationUsage - Organization usage policy
AllowAnyOrganization - Allow any organization

opts

...option.RequestOption

Optional request options

Example

grant := &management.CreateClientGrantRequestContent{
    ClientID: "abc123xyz",
    Audience: "https://api.example.com",
    Scope: []string{"read:users", "write:users"},
}

created, err := client.Management.ClientGrants.Create(context.TODO(), grant)
if err != nil {
    log.Fatalf("Failed to create client grant: %v", err)
}

fmt.Printf("Created grant ID: %s\n", created.GetID())

Update Client Grant

Updates an existing client grant’s scopes or organization settings.

func (c *Client) Update(
    ctx context.Context,
    id string,
    request *management.UpdateClientGrantRequestContent,
    opts ...option.RequestOption,
) (*management.UpdateClientGrantResponseContent, error)

ctx

context.Context

required

Context for the request

string

required

ID of the client grant to update

request

*management.UpdateClientGrantRequestContent

required

The fields to update:

Scope - Array of scopes
OrganizationUsage - Organization usage policy
AllowAnyOrganization - Allow any organization

opts

...option.RequestOption

Optional request options

Example

update := &management.UpdateClientGrantRequestContent{
    Scope: []string{"read:users", "write:users", "delete:users"},
}

updated, err := client.Management.ClientGrants.Update(
    context.TODO(),
    "cgr_1234567890",
    update,
)
if err != nil {
    log.Fatalf("Failed to update client grant: %v", err)
}

fmt.Printf("Updated scopes: %v\n", updated.Scope)

Delete Client Grant

Deletes a client grant, removing the M2M application’s access to the API.

func (c *Client) Delete(
    ctx context.Context,
    id string,
    opts ...option.RequestOption,
) error

ctx

context.Context

required

Context for the request

string

required

ID of the client grant to delete

opts

...option.RequestOption

Optional request options

Example

err := client.Management.ClientGrants.Delete(
    context.TODO(),
    "cgr_1234567890",
)
if err != nil {
    log.Fatalf("Failed to delete client grant: %v", err)
}

Organization Usage

Client grants can be configured to work with organizations:

deny - Deny all organization usage (default)
allow - Allow specific organizations
require - Require an organization

Example with Organizations

grant := &management.CreateClientGrantRequestContent{
    ClientID: "abc123xyz",
    Audience: "https://api.example.com",
    Scope: []string{"read:data"},
    OrganizationUsage: management.String("allow"),
    AllowAnyOrganization: management.Bool(false),
}

created, err := client.Management.ClientGrants.Create(context.TODO(), grant)
if err != nil {
    log.Fatalf("Failed to create grant: %v", err)
}

// Assign to specific organizations
err = client.Management.ClientGrants.Organizations.Add(
    context.TODO(),
    created.GetID(),
    &management.AddOrganizationsToClientGrantRequestContent{
        Organizations: []string{"org_1234567890"},
    },
)

Complete Example

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/auth0/go-auth0/v2/management"
)

func main() {
    client, err := management.New(
        context.TODO(),
        os.Getenv("AUTH0_DOMAIN"),
        management.WithClientCredentials(
            os.Getenv("AUTH0_CLIENT_ID"),
            os.Getenv("AUTH0_CLIENT_SECRET"),
        ),
    )
    if err != nil {
        log.Fatalf("Failed to create client: %v", err)
    }

    // Create a client grant
    grant := &management.CreateClientGrantRequestContent{
        ClientID: "your-m2m-client-id",
        Audience: "https://api.example.com",
        Scope: []string{"read:users", "write:users"},
    }

    created, err := client.Management.ClientGrants.Create(context.TODO(), grant)
    if err != nil {
        log.Fatalf("Failed to create grant: %v", err)
    }

    fmt.Printf("Grant created: %s\n", created.GetID())

    // List all grants for a client
    params := &management.ListClientGrantsRequestParameters{
        ClientID: management.String("your-m2m-client-id"),
    }

    page, err := client.Management.ClientGrants.List(context.TODO(), params)
    if err != nil {
        log.Fatalf("Failed to list grants: %v", err)
    }

    for _, g := range page.Results {
        fmt.Printf("Grant: %s - Audience: %s\n", g.GetID(), g.GetAudience())
    }

    // Update scopes
    update := &management.UpdateClientGrantRequestContent{
        Scope: []string{"read:users", "write:users", "delete:users"},
    }

    _, err = client.Management.ClientGrants.Update(
        context.TODO(),
        created.GetID(),
        update,
    )
    if err != nil {
        log.Fatalf("Failed to update grant: %v", err)
    }

    fmt.Println("Grant updated successfully")
}

Best Practices

Principle of Least Privilege - Only grant the minimum scopes required
Regular Audits - Periodically review and audit client grants
Scope Management - Define clear, granular scopes for your APIs
Organization Filtering - Use organization filtering when appropriate
Monitor Usage - Track which grants are being used and by whom

Clients - Manage M2M applications
Resource Servers - Define APIs and scopes
Organizations - Manage organizations
Client Credentials Flow

Authentication API

Management API

Management Resources

Types & Utilities

List Client Grants

Example

Get Client Grant

Example

Create Client Grant

Example

Update Client Grant

Example

Delete Client Grant

Example

Organization Usage

Example with Organizations

Complete Example

Best Practices

Build docs developers (and LLMs) love

Authentication API

Management API

Management Resources

Types & Utilities

Documentation Index

​List Client Grants

​Example

​Get Client Grant

​Example

​Create Client Grant

​Example

​Update Client Grant

​Example

​Delete Client Grant

​Example

​Organization Usage

​Example with Organizations

​Complete Example

​Best Practices

​Related Resources

Build docs developers (and LLMs) love

List Client Grants

Example

Get Client Grant

Example

Create Client Grant

Example

Update Client Grant

Example

Delete Client Grant

Example

Organization Usage

Example with Organizations

Complete Example

Best Practices

Related Resources