Skip to main content

Getting Started

Step 1: Sign Up​

Data Fiduciaries (DFs) must register on the Consent Manager portal using the appropriate environment:

Please ensure you register in the correct environment based on whether you are testing or going live.

Step 2: Get Credentials​

After completing the signup process:

  1. Log in using your registered email ID and password.
  2. Navigate to the “Credentials” page:
  3. Click the “Create Client” button.
  4. Provide a Client Name and submit.
  5. Your Client ID and Client Secret will be generated.

Why Are Client Credentials Required?​

Client Credentials are used for secure API authentication.

You will need:

  • Client ID
  • Client Secret

These credentials are required to:

  1. Generate an Access Token using the Token API.
  2. Use that Access Token to securely call:
    • Consent Request API
    • Consent Verify API
    • Other protected APIs

In short:

Client Credentials → Generate Access Token → Call Consent APIs

All Consent Manager APIs are protected and require a valid access token in the Authorization header.

⚠️ Important Security Note

The Client Secret is displayed only once at the time of creation and cannot be retrieved again.

  • Copy it immediately.
  • Store it securely in a secrets manager or vault.
  • Do not expose it in frontend or mobile applications.

Step 3: Generate Access Token​

All Consent Manager APIs are protected and require a valid Access Token.

You must generate an access token using your Client ID and Client Secret via HTTP Basic Authentication.

🔐 Authentication Mechanism​

The token API uses Basic Authentication.

Your client_id and client_secret must be:

  1. Concatenated using a colon

    client_id:client_secret

  2. Base64 encoded

  3. Sent in the Authorization header:

    Authorization: Basic <base64_encoded_value>

Token Endpoint​

Method: GET

Staging​

https://staging.indiaconsent.com/api/v1/auth/df/token

Production​

https://www.indiaconsent.com/api/v1/auth/df/token

Request Headers​

HeaderValue
Content-Typeapplication/json
AuthorizationBasic base64(client_id:client_secret)

⚠️ No request body is required.

Sample Request (Conceptual)​

GET /api/v1/auth/df/token
Authorization: Basic ZGYteHh4eHh4eDp5eXl5eXl5eXk=
Content-Type: application/json

Sample Response​

{  
 "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
 "tokenType": "Bearer",
 "expiresInSeconds": 900
}

🔹 Sample Code

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class TokenExample {
    public static void main(String[] args) throws IOException, InterruptedException {
        String clientId = "your_client_id";
        String clientSecret = "your_client_secret";
        String tokenUrl = "https://api.example.com/oauth/token";

        // Create Basic Auth header
        String auth = clientId + ":" + clientSecret;
        String encodedAuth = Base64.getEncoder().encodeToString(auth.getBytes());

        // Create request body
        String requestBody = "grant_type=client_credentials";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(tokenUrl))
            .header("Authorization", "Basic " + encodedAuth)
            .header("Content-Type", "application/x-www-form-urlencoded")
            .POST(HttpRequest.BodyPublishers.ofString(requestBody))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println("Response: " + response.body());
    }
}

Before calling the Consent Creation API, you must construct a Consent Request Payload in your backend application.

This payload defines:

  • Who is requesting consent

  • What data will be processed

  • For what purpose

  • Duration of consent

  • Any additional metadata

📌 Important​

  • The payload must strictly follow the Consent Request JSON Schema defined by Consent Manager.

  • Payload creation must happen on your backend server.

  • This payload will be used in Step 5: Call Consent Creation API.

What Should Be Included?​

The Consent Request Payload typically contains:

  • Unique request reference ID

  • Data Fiduciary (DF) details

  • Purpose of processing

  • Data categories

  • Consent validity period

  • Redirect / callback information

  • Optional metadata

Refer to the full JSON Schema below to understand mandatory and optional fields.

📄 Consent Request JSON Schema​

// CONSENT REQUEST SCHEMA HERE

🧾 Sample Payload​

// SAMPLE CONSENT REQUEST PAYLOAD HERE

⚠️ Validation Requirements​

Before sending the payload in Step 5:

  • Ensure all required fields are populated.

  • Validate field formats (dates, enums, identifiers).

  • Ensure reference IDs are unique.

  • Avoid sending null or unexpected attributes.

Failure to follow the schema may result in:

  • 400 Bad Request

  • Schema validation errors

  • Rejected consent creation

🔒 Security Considerations​

  • Do not generate this payload in frontend/mobile applications.

  • Avoid exposing internal identifiers.

  • Sanitize user-provided values before embedding them into the payload.

➡ Next Step​

In the next step, you will:

  • Use this generated payload

  • Attach your Access Token

  • Call the Consent Creation API

Once you have:

  • ✅ Generated the Access Token (Step 3)

  • ✅ Prepared the Consent Request Payload (Step 4)

You are now ready to create a Consent Request.

Endpoint​

Method: POST
URL:

/api/v1/df/consent-requests

Environment Base URLs​

Staging:

https://staging.indiaconsent.com/api/v1/df/consent-requests

Production:

https://www.indiaconsent.com/api/v1/df/consent-requests

Request Headers​

HeaderValue
Content-Typeapplication/json
AuthorizationBearer <accessToken>

Request Body​

The request body must contain the Consent Request Payload generated in Step 4.

// INSERT CONSENT REQUEST PAYLOAD HERE

Sample Request (Conceptual)​

POST /api/v1/df/consent-requests
Authorization: Bearer <accessToken>
Content-Type: application/json

{  
 // Consent Request Payload  
}

🔹 Sample Code Placeholder

// JAVA CONSENT CREATION CODE

Sample Response​

The API will generate a new Consent Request and return a response containing multiple attributes.

{  
 "requestId": "CR-20240218-12345",  
 "fidId": "FID-987654",  
 "dpHash": "a8f5f167f44f4964e6c998dee827110c",  
 "status": "CREATED",  
 "createdAt": "2026-02-18T10:15:30Z",  
 "expiresAt": "2026-03-18T10:15:30Z",  
 "redirectUrl": "https://consent.indiaconsent.com/notice/CR-20240218-12345"  
}

Important Response Attributes​

AttributeDescription
requestIdUnique identifier of the Consent Request
fidIdData Fiduciary identifier
dpHashHash representing the Data Principal context
statusCurrent state of consent request
redirectUrlURL to display the consent notice to the user

🚀 Most Important Field: redirectUrl​

The redirectUrl is the key output of this step.

This URL must be used by the Data Fiduciary’s UI to display the Consent Notice to the user.

What Happens Next?​

  • In Step 6, you will extract the redirectUrl from this response.

  • In Step 7, your application will open this URL to allow the user to Grant or Revoke consent.

Step 6: Extract Redirect URL​

After successfully calling the Consent Creation API (Step 5), the response will include multiple attributes related to the created consent request.

The most important field in the response is:

{  
 "redirectUrl": "https://consent.indiaconsent.com/notice/CR-20240218-12345"  
}

What is redirectUrl?​

The redirectUrl is a unique, system-generated URL that:

  • Displays the Consent Notice to the Data Principal

  • Allows the user to Grant or Revoke consent

  • Is securely mapped to the created consent request

Each consent request will generate a unique redirect URL.

What You Must Do​

  • Extract the redirectUrl value from the API response.

  • Store it temporarily in your backend or pass it securely to your frontend.

  • Use this URL in the next step to present the consent notice to the user.

⚠️ Do not modify the URL.
⚠️ Do not cache it beyond its validity period.

Example (Conceptual Flow)​

Call Consent API → Receive Response → Extract redirectUrl → Send to UI

Once you have the redirectUrl, your application must open it so the user can review and act on the consent notice.

Where Can It Be Opened?​

The redirectUrl can be opened in:

🌐 Web Applications​

  • Browser redirect

  • New tab

  • Popup window

  • Embedded iframe (if allowed by policy)

Example:

window.location.href = redirectUrl;

📱 Mobile Applications​

  • Mobile browser

  • In-app browser

  • WebView (Android/iOS)

  • Flutter WebView

  • React Native WebView

What Happens on the Consent Page?​

On the Consent Notice page, the user can:

  • Review purpose and data details

  • Grant consent

  • Revoke consent (if applicable)

After user action:

  • Consent Manager processes the decision

  • A consent receipt is generated

  • A webhook notification is sent to the Data Fiduciary (if configured)

Important Notes​

  • Ensure the user session context is maintained before redirecting.

  • Handle cases where user closes the browser without completing action.

  • Always rely on webhook or Consent Verify API to confirm final status.

Create Consent Request
↓
Receive redirectUrl
↓
Open Consent Notice
↓
User Grants / Revokes
↓
Webhook Notification Sent

Once the Data Principal Grants or Revokes consent via the Consent Notice UI, the Consent Manager will notify the Data Fiduciary (DF) by calling the configured Webhook URL.

This webhook delivers the final consent decision along with a cryptographically signed payload.

🔔 When Is the Webhook Triggered?​

The webhook is triggered when:

  • User grants consent

  • User revokes consent

  • Consent expires (if applicable)

📌 Webhook Endpoint (DF Side)​

During onboarding, the DF must configure a webhook URL in the Consent Manager dashboard.

Example:

https://yourdomain.com/api/webhooks/consent-status

This endpoint must:

  • Accept POST requests

  • Accept application/json

  • Be publicly accessible over HTTPS

Webhook Request​

Method: POST
Content-Type: application/json

Webhook Payload Schema​

{  
 "eventType": "CONSENT\_GRANTED | CONSENT\_REVOKED",  
 "requestId": "string",  
 "consentId": "string",  
 "fidId": "string",  
 "dpHash": "string",  
 "status": "GRANTED | REVOKED",  
 "timestamp": "ISO-8601 datetime",  
 "receipt": {  
   "receiptId": "string",  
   "issuedAt": "ISO-8601 datetime",  
   "receiptHash": "string",  
   "signature": "string"  
 }  
}

Sample Webhook Payload​

{  
 "eventType": "CONSENT\_GRANTED",  
 "requestId": "CR-20240218-12345",  
 "consentId": "CN-789456123",  
 "fidId": "FID-987654",  
 "dpHash": "a8f5f167f44f4964e6c998dee827110c",  
 "status": "GRANTED",  
 "timestamp": "2026-02-18T10:25:30Z",  
 "receipt": {  
   "receiptId": "RCPT-456123789",  
   "issuedAt": "2026-02-18T10:25:30Z",  
   "receiptHash": "3f79bb7b435b05321651daefd374cd21b0e8b9e8",  
   "signature": "MEUCIQDw..."  
 }  
}

🔐 Webhook Signature Verification​

To ensure authenticity:

  • Each webhook payload is digitally signed.

  • The DF must verify the signature using the Consent Manager’s public key.

  • Optionally validate the receipt hash for integrity.

  1. Verify the request is received over HTTPS.

  2. Validate signature using public key.

  3. Validate receipt hash.

  4. Ensure requestId matches an existing request.

  5. Ensure idempotency (avoid duplicate processing).

Expected DF Response​

Your webhook endpoint must return:

HTTP/1.1 200 OK

If a non-2xx response is returned:

  • Consent Manager may retry delivery.

  • Multiple attempts may occur.

🔁 Retry Policy (Recommended Behavior)​

  • If webhook fails, retry mechanism will attempt redelivery.

  • Ensure your endpoint is idempotent.

⚠️ Important Security Guidelines​

  • Do not trust payload without signature validation.

  • Do not expose webhook URL publicly without validation logic.

  • Maintain logs for audit purposes.

  • Store consent receipt securely for compliance.

User Grants / Revokes
↓
Consent Manager Generates Receipt
↓
Signed Webhook Sent to DF
↓
DF Verifies & Stores Consent Record

This completes the end-to-end consent flow:

  1. Sign Up

  2. Get Credentials

  3. Generate Access Token

  4. Create Payload

  5. Call Consent API

  6. Extract redirectUrl

  7. Open Consent Notice

  8. Receive Webhook