Signing Keys

Manage signing and encryption keys with the Go SDK

Manage cryptographic keys used for signing tokens and encrypting data in your Auth0 tenant.

Overview

The Keys client provides access to three types of keys:

type Client struct {
    CustomSigning *customsigning.Client  // Custom signing keys
    Encryption    *encryption.Client     // Encryption keys
    Signing       *signing.Client        // Standard signing keys
}

Signing Keys

Manage keys used to sign tokens (JWTs). Access via managementClient.Keys.Signing.

List Signing Keys

Retrieve all signing keys.

keys, err := managementClient.Keys.Signing.List(context.Background())
if err != nil {
    // Handle error
}

for _, key := range keys {
    fmt.Printf("Key ID: %s\n", key.GetKID())
    fmt.Printf("Current: %v\n", key.GetCurrent())
}

Get Signing Key

Retrieve a specific signing key by ID.

key, err := managementClient.Keys.Signing.Get(context.Background(), "key_abc123")
if err != nil {
    // Handle error
}
fmt.Printf("Algorithm: %s\n", key.GetAlgorithm())

Rotate Signing Key

Rotate the signing key to a new key.

newKey, err := managementClient.Keys.Signing.Rotate(context.Background())
if err != nil {
    // Handle error
}
fmt.Printf("New key ID: %s\n", newKey.GetKID())

Revoke Signing Key

Revoke a signing key to prevent its use.

err := managementClient.Keys.Signing.Revoke(context.Background(), "key_abc123")
if err != nil {
    // Handle error
}

Custom Signing Keys

Manage custom keys for signing tokens. Access via managementClient.Keys.CustomSigning.

Create Custom Signing Key

key, err := managementClient.Keys.CustomSigning.Create(context.Background(), &management.CreateCustomSigningKeyRequest{
    Algorithm: auth0.String("RS256"),
})
if err != nil {
    // Handle error
}
fmt.Printf("Created custom key: %s\n", key.GetKID())

List Custom Signing Keys

keys, err := managementClient.Keys.CustomSigning.List(context.Background())
if err != nil {
    // Handle error
}

for _, key := range keys {
    fmt.Printf("Custom Key ID: %s (Algorithm: %s)\n", key.GetKID(), key.GetAlgorithm())
}

Get Custom Signing Key

key, err := managementClient.Keys.CustomSigning.Get(context.Background(), "key_abc123")
if err != nil {
    // Handle error
}

Update Custom Signing Key

key, err := managementClient.Keys.CustomSigning.Update(context.Background(), "key_abc123", &management.UpdateCustomSigningKeyRequest{
    Name: auth0.String("Production Key"),
})
if err != nil {
    // Handle error
}

Delete Custom Signing Key

err := managementClient.Keys.CustomSigning.Delete(context.Background(), "key_abc123")
if err != nil {
    // Handle error
}

Encryption Keys

Manage keys used for encrypting sensitive data. Access via managementClient.Keys.Encryption.

List Encryption Keys

keys, err := managementClient.Keys.Encryption.List(context.Background())
if err != nil {
    // Handle error
}

for _, key := range keys {
    fmt.Printf("Encryption Key ID: %s\n", key.GetKID())
}

Get Encryption Key

key, err := managementClient.Keys.Encryption.Get(context.Background(), "key_abc123")
if err != nil {
    // Handle error
}

Create Encryption Key

key, err := managementClient.Keys.Encryption.Create(context.Background(), &management.CreateEncryptionKeyRequest{
    Type: auth0.String("customer-provided-root-key"),
})
if err != nil {
    // Handle error
}
fmt.Printf("Created encryption key: %s\n", key.GetKID())

Delete Encryption Key

err := managementClient.Keys.Encryption.Delete(context.Background(), "key_abc123")
if err != nil {
    // Handle error
}

Key Properties

Keys typically have the following properties:

• KID: Key identifier
• Algorithm: Cryptographic algorithm (RS256, RS384, HS256, etc.)
• Current: Whether this is the current active key
• Cert: PEM-encoded certificate (for public keys)
• Thumbprint: Certificate thumbprint
• CreatedAt: When the key was created
• RevokedAt: When the key was revoked (if applicable)

Complete Example

Here’s a complete example of managing signing keys:

package main

import (
    "context"
    "fmt"
    "log"
    
    "github.com/auth0/go-auth0/v2/management"
)

func main() {
    managementClient, err := management.New(
        "yourtenant.auth0.com",
        management.WithClientCredentials(clientID, clientSecret),
    )
    if err != nil {
        log.Fatal(err)
    }
    
    ctx := context.Background()
    
    // List all signing keys
    keys, err := managementClient.Keys.Signing.List(ctx)
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Println("Current signing keys:")
    for _, key := range keys {
        fmt.Printf("  - %s (current: %v)\n", key.GetKID(), key.GetCurrent())
    }
    
    // Rotate to a new key
    fmt.Println("\nRotating signing key...")
    newKey, err := managementClient.Keys.Signing.Rotate(ctx)
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("New active key: %s\n", newKey.GetKID())
    fmt.Printf("Algorithm: %s\n", newKey.GetAlgorithm())
    
    // List keys again to see the rotation
    keys, err = managementClient.Keys.Signing.List(ctx)
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Println("\nAfter rotation:")
    for _, key := range keys {
        fmt.Printf("  - %s (current: %v)\n", key.GetKID(), key.GetCurrent())
    }
}

Key Rotation Best Practices

1. Regular Rotation: Rotate signing keys periodically (e.g., every 90 days)
2. Graceful Transition: Keep old keys active for a period to allow token validation during transition
3. Monitor Usage: Track which keys are being used for signing and validation
4. Revoke Old Keys: Revoke keys that are no longer needed
5. Backup Keys: Store key information securely before rotation

Supported Algorithms

Common signing algorithms:

• RS256: RSA with SHA-256 (recommended)
• RS384: RSA with SHA-384
• RS512: RSA with SHA-512
• HS256: HMAC with SHA-256
• HS384: HMAC with SHA-384
• HS512: HMAC with SHA-512
• ES256: ECDSA with SHA-256
• ES384: ECDSA with SHA-384
• ES512: ECDSA with SHA-512