Mavim API Access Customer setup guide

Who this guide is for (API consumers)

This guide applies only if your organization wants to call Mavim Cloud APIs from your own applications or integrations (for example, custom apps or automation).

When Mavim is installed in your tenant, Mavim’s own multi-tenant applications appear as enterprise applications. Those are Mavim-owned and are used by Mavim products.

To consume Mavim APIs with an application token (Client Credentials), you create a separate app registration in your own tenant. That app registration is:

• Owned and managed by you (the customer), not by Mavim
• Not required for normal use of Mavim products
• Use-case specific — only needed if you are an API consumer building or integrating something that calls Mavim APIs

Mavim does not impose this app registration on customers. Follow this guide only when you need programmatic API access.

To successfully integrate with Mavim APIs, you must:

1. Create an app registration in Microsoft Entra ID.
2. Configure an authentication credential (Client Secret, Certificate, or Federated Credential).
3. Assign the api.access application permission.
4. Grant administrator consent.
5. Provide the Application (Client) ID to Mavim for allow-listing.
6. Obtain an access token and consume the Mavim APIs.

Important: Mavim only accepts app-only tokens that contain the api.access role and originate from an allow-listed application. 

Purpose

This guide is intended for:

1. Microsoft Entra ID Administrators
2. Azure Administrators
3. Integration Engineers
4. Application Developers

Mavim API Information

Prerequisites

Before you begin, ensure you have:

1. Access to the Microsoft Entra Admin Center or Azure Portal.
2. Permission to create app registrations (for example Application Developer, Application Administrator, or Global Administrator).
3. Permission to grant admin consent for application permissions (typically Global Administrator, Privileged Role Administrator, or Cloud Application Administrator).

Configuration Process

The integration consists of the following steps:

1. Create an App Registration.
2. Configure an authentication credential.
3. Add the Mavim API permission.
4. Grant Admin Consent.
5. Register the Application ID with Mavim.
6. Request access tokens.
7. Call the Mavim APIs.

Step 1 - Create an App Registration

Configuration

Configure the application as follows:

Select Register.

Copy and store: Application (client) ID 

You will send the Application (client) ID to Mavim in one of the later steps, so this value will be required later.

Step 2 - Configure Authentication

Mavim supports the following authentication methods:

1. Client Secret
2. Certificate
3. Federated Credential (Managed Identity)

At least one authentication method must be configured.

Option A - Client Secret Authentication

Important: The secret Value is shown only once. If it is lost, create a new secret. Do not send the client secret to Mavim. Only the Application (client) ID is shared.  

Option B - Certificate Authentication

If your security policy requires certificate-based authentication instead of (or in addition to) a client secret, follow these steps. Otherwise, skip this step.  

Generate a self-signed certificate (if you don't already have one)

PowerShell (Windows):

$cert = New-SelfSignedCertificate `
        -Subject "CN=YourCompany-MavimApiClient" `
        -CertStoreLocation "Cert:\CurrentUser\My" `
        -KeyExportPolicy Exportable `
        -KeySpec Signature `
        -KeyLength 2048 `
        -NotAfter (Get-Date).AddMonths(12)

# Export public key (.cer) for upload
Export-Certificate -Cert $cert -FilePath ".\MavimApiClient.cer"

# (Optional) Export private key (.pfx) for your application
$pw = ConvertTo-SecureString -String "YourStrongPassword" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath ".\MavimApiClient.pfx" -Password                $pw  

Linux / macOS (OpenSSL):

openssl req -x509 -newkey rsa:2048 \
         -keyout MavimApiClient.key \
         -out MavimApiClient.cer \                                                                                                               -days 365 -nodes \
         -subj "/CN=YourCompany-MavimApiClient"

You can also use a certificate from your organization's CA or a public CA.

 Upload the certificate to your app registration 

After upload, you can note the Thumbprint for your own app configuration (optional). Your application authenticates by signing the client assertion with the certificate’s private key; Entra verifies it using the public certificate you uploaded. Important: Store the private key (.pfx / .key) securely. Never commit it to source control.

Note: Mavim does not require a certificate specifically. It requires a valid app-only token with api.access from an allow-listed app. Certificate vs secret is about how your tenant authenticates the client to Entra, not about a special Mavim permission.  

Using the certificate in a token request

Replace client_secret with a client assertion (a JWT signed by the certificate's private key). Most identity libraries handle this automatically.

MSAL (.NET / C#):

var certificate = new X509Certificate2("MavimApiClient.pfx", "YourStrongPassword");

var app = ConfidentialClientApplicationBuilder
       .Create("{your-application-client-id}")
       .WithCertificate(certificate)
      .WithAuthority($"https://login.microsoftonline.com/{your-tenant-id}")   .Build();

var result = await app.AcquireTokenForClient(
new[] {                          "https://adapps.mavimcloud.com/mavim.cloud.identity.core/.default" })
.ExecuteAsync();

Option C - Federated Credential (User-assigned Managed Identity)

If your application runs on Azure compute (VMs, AKS, App Service, Azure Functions), you can eliminate secrets and certificates entirely by federating the app registration with a User-assigned Managed Identity. If your security policy requires federated-based authentication instead of (or in addition to) a client secret and/or certificate, follow these steps. Otherwise, skip this step. 

How it works

Azure workload (VM / AKS / App Service) → User-assigned Managed Identity → Federated credential on your App Registration → Entra ID issues token with aud = Mavim Identity Core Access

Prerequisites

1. A User-assigned Managed Identity (UAMI) created in your Azure subscription.
2. The UAMI assigned to the Azure resource that will call Mavim APIs.
3. Note the UAMI's Client ID and Object (principal) ID.

Add the federated credential

1. In your app registration, open Certificates & secrets.

2. Select the Federated credentials tab.

3. Select + Add credential.

4. Choose the scenario (see table below) and fill in the fields.

1. Select Add.

Tip: If the Azure Portal shows a Managed Identity scenario picker, select it and choose the User-assigned Managed Identity from the dropdown — the fields are populated automatically.

Using the federated credential in a token request

MSAL (.NET / C#):

var miCredential = new ManagedIdentityCredential("{user-assigned-mi-client-id}"); 
 
var app = ConfidentialClientApplicationBuilder 
    .Create("{your-app-registration-client-id}") 
    .WithClientAssertion(async (cancel) => 
    { 
        var token = await miCredential.GetTokenAsync( 
            new TokenRequestContext(new[] { "api://AzureADTokenExchange/.default" }), cancel); 
        return token.Token; 
    }) 
    .WithAuthority($"https://login.microsoftonline.com/{your-tenant-id}") 
    .Build(); 
 
var result = await app.AcquireTokenForClient( 
    new[] { "https://adapps.mavimcloud.com/mavim.cloud.identity.core/.default" }) 
    .ExecuteAsync(); 

Azure.Identity (simplified):

var miCredential = new ManagedIdentityCredential("{user-assigned-mi-client-id}"); 
 
var credential = new ClientAssertionCredential( 
    "{your-tenant-id}", 
    "{your-app-registration-client-id}", 
    async (cancel) => 
    { 
        var token = await miCredential.GetTokenAsync( 
            new TokenRequestContext(new[] { "api://AzureADTokenExchange/.default" }), cancel); 
        return token.Token; 
    }); 
 
var tokenResult = await credential.GetTokenAsync( 
    new TokenRequestContext( 
        new[] { "https://adapps.mavimcloud.com/mavim.cloud.identity.core/.default" })); 

Note: No secret or certificate is needed on the machine. The Managed Identity handles the trust chain.

Step 3 -  Add the Mavim api.access application permission 

1. In your app registration, open API permissions.
2. Select + Add a permission.
3. Open the APIs my organization uses tab (or search by name / Application ID).
4. Search for Mavim Cloud – Identity Core Access. If it does not appear by name, paste the Application (client) ID: 51fb1b02-5c75-445f-9225-807e50623cd4.
5. Select Application permissions (not Delegated permissions).
6. Select api.access (display name: Mavim API Access).
7. Select Add permissions

Expected Result

Step 4 - Grant Admin Consent

Why This Is Required

Without Admin Consent:

• The api.access role will not be included in access tokens.
• Mavim API requests will be rejected.

Step 5 - Register the Application with Mavim

Provide the following information to your Mavim representative or Mavim Support (servicedesk@mavim.com).

What Mavim does next:

Mavim will allow-list the Application (Client) ID within your tenant.

Only allow-listed applications are authorized to access Mavim APIs.

Mavim stores (allow-lists) your Application (client) ID for your tenant. Only after this registration will tokens issued for your app be accepted for app-only API calls.

Do not share the client secret with Mavim.

Step 6 - Obtain an access token using client secret

Token request 

POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token 
Content-Type: application/x-www-form-urlencoded 
 
client_id={your-application-client-id} 
&client_secret={your-client-secret} 
&grant_type=client_credentials 
&scope=https://adapps.mavimcloud.com/mavim.cloud.identity.core/.default

Expected Token Claims

The resulting access token should contain the following claims:

Step 7 - Call Mavim APIs

Authorization: Bearer {access_token} 

Use the API base URL and endpoints provided by your Mavim contact.  

Validation Checklist

Troubleshooting

Security Recommendations

To maintain a secure integration:

• • Treat the client secret as a credential; rotate it regularly and store it only in a secrets manager.
  • Prefer certificate credentials over client secrets for production where your policies allow.
  • Restrict who can manage the app registration (Owners).
  • Do not embed secrets in source control, tickets, or email.
  • Share only the Application (client) ID with Mavim—never the secret.