Skip to main content
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
​
id
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
​
id
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
​
id
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

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

Build docs developers (and LLMs) love

Get started for freeTalk to us