Developer Docs

Overview

Identity providers are essential for Express API authentication. They define how users authenticate and provide the necessary configuration for JWT token validation. Each provider includes an issuer, audience, and JWKS URI for secure token verification.

You must configure at least one identity provider before users can authenticate with your Express API application.

Create Identity Provider

Create a new identity provider configuration for your application.

cURL

curl -X POST 'https://tee.express.magiclabs.com/v1/identity/provider' \
  -H 'Content-Type: application/json' \
  -H 'X-Magic-Secret-Key: your-magic-secret-key' \
  -d '{
    "issuer": "https://your-auth-provider.com",
    "audience": "your-app-audience",
    "jwks_uri": "https://your-auth-provider.com/.well-known/jwks.json"
  }'

Response:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "issuer": "https://your-auth-provider.com",
  "audience": "your-app-audience",
  "jwks_uri": "https://your-auth-provider.com/.well-known/jwks.json"
}

Request Parameters

issuer

string

required

The issuer identifier for your OIDC provider. This should match the iss claim in JWT tokens.

audience

string

required

The audience identifier for your application. This should match the aud claim in JWT tokens.

jwks_uri

string

required

The JSON Web Key Set URI where Magic can fetch public keys for JWT verification.

Response Fields

string

Unique identifier for the created identity provider.

issuer

string

The issuer identifier returned from the request.

audience

string

The audience identifier returned from the request.

jwks_uri

string

The JWKS URI returned from the request.

Get Identity Providers

Retrieve all configured identity providers for your application.

cURL

curl -X GET 'https://tee.express.magiclabs.com/v1/identity/provider' \
  -H 'X-Magic-Secret-Key: your-magic-secret-key' 

Response:

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "issuer": "https://your-auth-provider.com",
    "audience": "your-app-audience",
    "jwks_uri": "https://your-auth-provider.com/.well-known/jwks.json"
  }
]

Response Fields

providers

array

Array of identity provider objects.

Show Provider object

string

Unique identifier for the identity provider.

issuer

string

The issuer identifier for the provider.

audience

string

The audience identifier for the provider.

jwks_uri

string

The JWKS URI for the provider.

Update Identity Provider

Update an existing identity provider configuration.

cURL

curl -X PATCH 'https://tee.express.magiclabs.com/v1/identity/provider/{id}' \
  -H 'Content-Type: application/json' \
  -H 'X-Magic-Secret-Key: your-magic-secret-key' \
  -d '{
    "issuer": "https://updated-auth-provider.com",
    "audience": "updated-app-audience",
    "jwks_uri": "https://updated-auth-provider.com/.well-known/jwks.json"
  }'

Response:

{
  "id": "your-passed-in-id",
  "issuer": "https://updated-auth-provider.com",
  "audience": "updated-app-audience",
  "jwks_uri": "https://updated-auth-provider.com/.well-known/jwks.json"
}

Request Parameters

string

required

The unique identifier of the identity provider to update.

issuer

string

required

The updated issuer identifier for your OIDC provider.

audience

string

required

The updated audience identifier for your application.

jwks_uri

string

required

The updated JSON Web Key Set URI.

Response Fields

string

The identity provider ID (unchanged).

issuer

string

The updated issuer identifier.

audience

string

The updated audience identifier.

jwks_uri

string

The updated JWKS URI.

Delete Identity Provider

Remove an identity provider configuration from your application.

cURL

curl -X DELETE 'https://tee.express.magiclabs.com/v1/identity/provider/{id}' \
  -H 'X-Magic-Secret-Key: your-magic-secret-key' 

Response:

No content (204 status code)

Request Parameters

string

required

The unique identifier of the identity provider to delete.

Deleting an identity provider will prevent users authenticated through that provider from accessing your Express API. Ensure you have alternative authentication methods configured before deletion.

Common Use Cases

Auth0 Integration

{
  "issuer": "https://your-domain.auth0.com/",
  "audience": "https://your-api-identifier",
  "jwks_uri": "https://your-domain.auth0.com/.well-known/jwks.json"
}

Firebase Auth Integration

{
  "issuer": "https://securetoken.google.com/your-project-id",
  "audience": "your-project-id",
  "jwks_uri": "https://www.googleapis.com/service_accounts/v1/jwk/[email protected]"
}

Custom OIDC Provider

{
  "issuer": "https://your-custom-provider.com",
  "audience": "your-app-client-id",
  "jwks_uri": "https://your-custom-provider.com/.well-known/jwks.json"
}

Server Wallets

Express API

Core API

Identity Provider

Overview

Create Identity Provider

Request Parameters

Response Fields

Get Identity Providers

Response Fields

Update Identity Provider

Request Parameters

Response Fields

Delete Identity Provider

Request Parameters

Common Use Cases

Auth0 Integration

Firebase Auth Integration

Custom OIDC Provider

​Overview

​Create Identity Provider

​Request Parameters

​Response Fields

​Get Identity Providers

​Response Fields

​Update Identity Provider

​Request Parameters

​Response Fields

​Delete Identity Provider

​Request Parameters

​Common Use Cases

​Auth0 Integration

​Firebase Auth Integration

​Custom OIDC Provider

Overview

Create Identity Provider

Request Parameters

Response Fields

Get Identity Providers

Response Fields

Update Identity Provider

Request Parameters

Response Fields

Delete Identity Provider

Request Parameters

Common Use Cases

Auth0 Integration

Firebase Auth Integration

Custom OIDC Provider