Android integration guide

01Before you start

You need two things from your Datacove tenant administrator before writing any code.

02How it fits together

The user never sets a password. They prove they own a phone number or email address with a six-digit code, and the app receives a token pair it keeps refreshing for as long as the user stays signed in.

03Sign in with OTP

Offer phone, email, or both. They work the same way: request a code, verify it, and activate the account the first time it signs in. Each phone number or email address maps to one account per tenant, created automatically on the first request.

Phone number

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 1800
}

interface AuthApi {
    @POST("auth/v1/mobile/request-otp")
    suspend fun requestMobileOtp(@Body body: RequestMobileOtp): Response<Unit>

    @POST("auth/v1/mobile/verify-otp")
    suspend fun verifyMobileOtp(@Body body: VerifyMobileOtp): TokenPair

    @POST("auth/v1/activate")
    suspend fun activate(): TokenPair          // Bearer token added by the interceptor

    @POST("auth/v1/refresh")
    suspend fun refresh(@Body body: RefreshRequest): TokenPair
}

data class RequestMobileOtp(val phoneNumber: String, val name: String? = null, val channel: String = "sms")
data class VerifyMobileOtp(val phoneNumber: String, val otp: String, val channel: String = "sms")
data class RefreshRequest(val refreshToken: String)
data class TokenPair(val accessToken: String, val refreshToken: String, val expiresIn: Int)

// Sign-in routes need the app's API key; everything else carries the user's token.
class ApiKeyInterceptor(private val apiKey: String) : Interceptor {
    override fun intercept(chain: Interceptor.Chain): okhttp3.Response =
        chain.proceed(chain.request().newBuilder().header("x-api-key", apiKey).build())
}

Email

Identical to the phone flow, with an email address instead of a number and no channel choice. Requesting a new code within 60 seconds of the last one returns 429.

{ "email": "jane@example.com", "name": "Jane Doe" }

{ "email": "jane@example.com", "otp": "123456" }

Activate and load the profile

A brand-new account comes back from verify with status: "CREATED" in its access token. Call activate once to move it to ACTIVE; it returns a fresh token pair that replaces the one you just stored. The call is idempotent, so if you're unsure whether it succeeded (a timeout, a dropped connection), just call it again.

{
  "name": "Jane Doe",
  "phone": "919876543210",
  "country": "IN",
  "timezone": "Asia/Kolkata",
  "status": "ACTIVE",
  "wallet": { "WALLET": 25, "TRIAL": 0, "SUBSCRIPTION": 0 }
}

To edit the name or timezone, use PATCH /users/v1/profile. To let a user delete their own account, use DELETE /users/v1/account.

04Keeping the session alive

Access tokens last 30 minutes. Refresh tokens last 7 days and change every time you use one, so a user who opens the app at least once a week stays signed in indefinitely.

{ "refreshToken": "eyJhbGciOiJIUzI1NiIs..." }

Rules for a well-behaved client

• Store tokens securely. Use DataStore or SharedPreferences encrypted with a key from the Android Keystore. Never log them.
• Refresh proactively. Refresh about a minute before expiresIn elapses, and also when any request returns 401, then retry that request once.
• Refresh one at a time. If several requests fail at once, they should all wait for a single refresh rather than each starting their own. Two refreshes that arrive within 30 seconds of each other with the same token both succeed and return the same new token. Anything later with an old token is treated as a stolen token and ends the session.
• Persist before you use. Write the new pair to storage before continuing, so a crash can't leave the app holding a refresh token that's already been replaced.

class TokenAuthenticator(
    private val store: TokenStore,          // encrypted persistence
    private val authApi: AuthApi,           // a separate Retrofit instance without this authenticator
) : Authenticator {
    private val mutex = Mutex()

    override fun authenticate(route: Route?, response: okhttp3.Response): Request? = runBlocking {
        val rejected = response.request.header("Authorization")?.removePrefix("Bearer ")
        val tokens = mutex.withLock {
            val current = store.read() ?: return@withLock null
            // Another request already refreshed while we were waiting: reuse its result.
            if (current.accessToken != rejected) return@withLock current
            try {
                authApi.refresh(RefreshRequest(current.refreshToken)).also { store.write(it) }
            } catch (e: HttpException) {
                if (e.code() == 401) store.clear()   // session is over; send the user to sign-in
                null
            }
        } ?: return@runBlocking null
        response.request.newBuilder().header("Authorization", "Bearer ${tokens.accessToken}").build()
    }
}

When a refresh is rejected

A 401 from refresh, or from any authenticated request, carries a machine-readable code inside error. Use it to tell the user why they were signed out.

{
  "statusCode": 401,
  "timestamp": "2026-10-02T09:30:00.000Z",
  "path": "/api/auth/v1/refresh",
  "error": {
    "statusCode": 401,
    "error": "Unauthorized",
    "message": "You were signed out because this account signed in on another device.",
    "code": "SESSION_EVICTED"
  }
}

Devices and signing out

An account can be signed in on up to 5 devices at once. Signing in on a sixth ends the least recently created session. The same endpoints let you build a "signed-in devices" screen:

05Running workflows

A workflow is an AI task with a defined set of inputs. Fetch its definition, render a form from its inputs, then execute it. Each run costs the credits configured for that workflow, deducted from wallet.WALLET.

Discover workflows

GET /workflows/v1/:pageNo/:pageSize returns { data, meta }, filtered to what your tenant offers. Optional query parameters: search, category, featured. Then fetch one by its id, for example GET /workflows/v1/wf-sec-001, to get its inputs.

Build the form from inputs

[
  {
    "key": "url",
    "label": "Website address",
    "type": "text",
    "placeholder": "https://example.com",
    "validation": { "required": true }
  },
  {
    "key": "document",
    "label": "Document",
    "type": "file",
    "fileOptions": { "accept": ".pdf,.docx", "maxSizeMb": 10, "multiple": false }
  }
]

interface WorkflowApi {
    @POST("workflows/v1/execute")
    suspend fun execute(@Body body: ExecuteRequest): JsonObject

    @Multipart
    @POST("workflows/v1/execute")
    suspend fun executeWithFiles(
        @Part("id") id: RequestBody,                 // plain text
        @Part("input") input: RequestBody,           // JSON string of the non-file inputs
        @Part files: List<MultipartBody.Part>,       // one part per file input, named by key
    ): JsonObject
}

data class ExecuteRequest(val id: String, val input: Map<String, Any?>)

// Text input
val result = workflowApi.execute(ExecuteRequest("wf-sec-001", mapOf("url" to "https://example.com")))

// File input: "document" is the input's key
val text = "text/plain".toMediaType()
val filePart = MultipartBody.Part.createFormData(
    "document", "contract.pdf", file.asRequestBody("application/pdf".toMediaType()),
)
val started = workflowApi.executeWithFiles(
    id = "wf-sec-008".toRequestBody(text),
    input = "{}".toRequestBody(text),            // no non-file inputs on this workflow
    files = listOf(filePart),
)

POST /api/workflows/v1/execute HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{ "id": "wf-sec-001", "input": { "url": "https://example.com" } }

Two kinds of response

Each workflow always responds the same way, so a client can simply check for eventId in the response.

06Getting report results

Use the realtime channel to be told the moment a report is ready, and keep polling as a fallback. Both use the eventId from execute.

A user's past runs are listed by GET /workflows/reports/v1/history/:page/:limit.

07Google Play billing

Apps can sell two kinds of product through Play Billing. Your tenant administrator creates both in the Datacove catalog, using the same product ids you set up in the Play Console.

Trial and entitlement

Workflows covered by a plan are available while the user has an active trial or an active plan. Without either, executing one returns 403 with code: "ENTITLEMENT_INACTIVE". Read the state once at launch and after every purchase:

{
  "trial": { "status": "active", "startedAt": "2026-10-01T08:00:00.000Z", "expiresAt": "2026-10-08T08:00:00.000Z" },
  "entitlement": { "status": "none" },
  "canExecuteGatedWorkflow": true,
  "serverTime": "2026-10-02T09:30:00.000Z"
}

Purchases

1. Launch the purchase with Play Billing, setting setObfuscatedAccountId() to the user's Datacove user id (the userId claim in the access token). This is recommended rather than required: it ties the purchase to the user inside Google's own records.
2. Confirm it with the backend as soon as Play Billing reports PURCHASED: call verify-purchase with the purchase token and product id.
3. Don't acknowledge it yourself. The backend acknowledges every purchase it verifies. For a credit package, call consumeAsync after a 200 so the user can buy the same package again. Leave subscriptions alone.
4. Recover unfinished purchases. On every launch, call queryPurchasesAsync and send any purchase you haven't confirmed yet through verify-purchase. Verifying the same purchase twice is safe; it is only ever granted once.

{ "kind": "credit_package", "creditsGranted": 500 }

{
  "kind": "service_entitlement",
  "entitlementStatus": "active",
  "currentPeriodEnd": "2026-11-02T09:30:00.000Z"
}

// 1. Launch, tagging the purchase with the Datacove user id
val params = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(listOf(productParams))
    .setObfuscatedAccountId(datacoveUserId)
    .build()
billingClient.launchBillingFlow(activity, params)

// 2-3. Confirm each completed purchase with the backend
override fun onPurchasesUpdated(result: BillingResult, purchases: MutableList<Purchase>?) {
    purchases.orEmpty()
        .filter { it.purchaseState == Purchase.PurchaseState.PURCHASED }
        .forEach { purchase -> scope.launch { confirm(purchase) } }
}

suspend fun confirm(purchase: Purchase) {
    val productId = purchase.products.first()
    val granted = paymentApi.verifyPurchase(
        VerifyPurchase(platform = "google_play", platformProductId = productId, purchaseToken = purchase.purchaseToken),
    )
    if (granted.kind == "credit_package") {
        // Consume so the same package can be bought again. The server has already acknowledged it.
        billingClient.consumePurchase(ConsumeParams.newBuilder().setPurchaseToken(purchase.purchaseToken).build())
    }
    refreshWalletAndEntitlement()
}

// 4. On launch, retry anything that never reached the backend
billingClient.queryPurchasesAsync(QueryPurchasesParams.newBuilder().setProductType(ProductType.INAPP).build()) { _, list ->
    list.filter { it.purchaseState == Purchase.PurchaseState.PURCHASED }.forEach { scope.launch { confirm(it) } }
}

Store setup

Done once per app by whoever administers the tenant, before purchases can be verified.

1. In Google Cloud, enable the Google Play Android Developer API, create a service account, and download its JSON key.
2. In the Play Console under Setup → API access, link that project and grant the service account View financial data and Manage orders and subscriptions.
3. Create a Pub/Sub topic, grant google-play-developer-notifications@system.gserviceaccount.com the Publisher role on it, and select it under Monetization setup → Real-time developer notifications.
4. Add a push subscription to that topic that delivers to https://<api-host>/webhooks/google-play (webhooks live outside the /api prefix; include any deployment path prefix). Enable authentication on it so the backend can verify that the messages come from Google.
5. Save the credentials with PATCH /tenants/v1/:id/google-play-config: packageName, serviceAccountEmail, serviceAccountPrivateKey and pubSubTopic.
6. Create the catalog: credit packages through /pricing-config (provider google_play, with iapCreditPackages) and plans through /service-entitlement-products (with platformProductIds.googlePlay). Each product id must match the Play Console exactly.

08Errors

Every error uses the same envelope. Branch on the HTTP status first, then on error.code when it's present.

{
  "statusCode": 403,
  "timestamp": "2026-10-02T09:30:00.000Z",
  "path": "/api/workflows/v1/execute",
  "error": {
    "code": "ENTITLEMENT_INACTIVE",
    "message": "Your trial has ended and no active subscription was found for this service."
  }
}

09Launch checklist

1. The ANDROID API key is injected at build time and never logged.
2. Tokens are stored encrypted, and every refresh saves the new pair before it's used.
3. Refresh is single-flight, and 401 handling reads error.code to show the right sign-out message.
4. File inputs respect fileOptions before upload, and execute uses multipart.
5. Report runs use the realtime channel with a polling fallback that keeps going for at least 20 minutes.
6. Purchases set setObfuscatedAccountId, are confirmed with verify-purchase, credit packages are consumed after a 200, and unfinished purchases are retried on launch.
7. The paywall is driven by canExecuteGatedWorkflow and serverTime, not the device clock.