Sign in with Daakiaa· Developer guideDaakiaa API →

Overview

Sign in with Daakiaa lets people sign in to your app or website with the Daakiaa account they already use for mail, the way “Sign in with Google” works. Your app never sees their password: they sign in on Daakiaa's own page (with 2-step verification, passkeys and their organization's rules), allow your app once, and come back with a code your server exchanges for tokens.

It is standard OpenID Connect 1.0 with the authorization code flow and PKCE, so any OpenID Connect library works: point it at the issuer and it finds everything else.

Issuer:     https://mail.daakiaa.com
Discovery:  https://mail.daakiaa.com/.well-known/openid-configuration

Your app learns a stable id for the person (sub), and, if it asks and they allow it, their email address, name, and organization.

Quick start

  1. 1
    Make an app

    An organization's admin makes apps for its own people in Admin → Company → Sign-in apps. Apps for anyone with a Daakiaa account are made by Daakiaa (platform console → Sign in with Daakiaa); ask Daakiaa support.

    • Kind: a website with a server gets a client secret; a phone, desktop or single-page app gets none (see below).
    • Return addresses (redirect URIs): every address your app may come back to, exactly as it sends it, e.g. https://erp.example.com/auth/daakiaa/callback.
    • Scopes: what the app may ask for (email, name, organization, staying signed in).
  2. 2
    Keep the client ID and secret

    The client ID (dk_app_…) is public. The client secret (dk_secret_…) is shown once: keep it in your server's settings, never in a web page, a phone app or a repository.

    DAAKIAA_ISSUER=https://mail.daakiaa.com
    DAAKIAA_CLIENT_ID=dk_app_…
    DAAKIAA_CLIENT_SECRET=dk_secret_…
    DAAKIAA_REDIRECT_URI=https://erp.example.com/auth/daakiaa/callback
  3. 3
    Set up your OpenID Connect library

    Give it the issuer, client ID, secret and return address; turn on PKCE (S256), state and nonce. See code examples.

  4. 4
    Add the button

    A “Sign in with Daakiaa” button on your sign-in page that starts the flow (design).

  5. 5
    Use sub as the person's id

    Store the person under sub. It never changes, even if their address does, and is never given to anyone else. Use the email to show and to contact them.

Endpoints

All are on the issuer's address. Libraries read them from the discovery document.

EndpointAddressUse
discovery/.well-known/openid-configurationEverything below, and what is supported.
authorization/oauth/authorizeSend the person here (browser; GET, or a form POST).
token/oauth/tokenYour server trades the code or a refresh token for tokens (POST, form).
userinfo/oauth/userinfoWho the access token's person is (GET or POST, Bearer).
jwks/oauth/jwksPublic keys to check ID tokens (RS256).
revocation/oauth/revokeSign a person out of your app (RFC 7009).

Supported: response_type=code only, code_challenge_method=S256 only (PKCE is required for every app), client authentication client_secret_basic, client_secret_post, or none for phone and single-page apps. The answer names its issuer in an iss parameter (RFC 9207).

The sign-in, step by step

What your library does for you, in plain HTTP.

1. Before sending the person

Make a random code_verifier (43–128 characters), its code_challenge = base64url(SHA-256(verifier)), a random state and nonce. Keep all three in the person's session on your server.

2. Send them to Daakiaa

https://mail.daakiaa.com/oauth/authorize
  ?response_type=code
  &client_id=dk_app_…
  &redirect_uri=https%3A%2F%2Ferp.example.com%2Fauth%2Fdaakiaa%2Fcallback
  &scope=openid%20email%20profile
  &state=<state>
  &nonce=<nonce>
  &code_challenge=<code_challenge>
  &code_challenge_method=S256

They sign in if needed, see what your app asks for, and press Allow (only the first time). Daakiaa's own verified apps skip that screen.

3. They come back

https://erp.example.com/auth/daakiaa/callback?code=dk_code_…&state=<state>&iss=https%3A%2F%2Fmail.daakiaa.com

Check that state is the one you kept and iss is the issuer. If they cancelled or may not sign in, you get error=access_denied instead.

4. Your server trades the code (within a minute)

curl -u "dk_app_…:dk_secret_…" \
  -d grant_type=authorization_code \
  -d code=dk_code_… \
  -d redirect_uri=https://erp.example.com/auth/daakiaa/callback \
  -d code_verifier=<code_verifier> \
  https://mail.daakiaa.com/oauth/token
{
  "access_token": "dk_at_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid email profile",
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6…"
}

5. Check the ID token

Verify its RS256 signature with the key from /oauth/jwks whose kid it names, then that iss is the issuer,aud is your client ID, exp has not passed, and nonce is the one you kept. Libraries do all of this.

{
  "iss": "https://mail.daakiaa.com",
  "sub": "dk8Jq2…",
  "aud": "dk_app_…",
  "azp": "dk_app_…",
  "iat": 1762500000,
  "exp": 1762503600,
  "auth_time": 1762499940,
  "nonce": "<nonce>",
  "at_hash": "…",
  "email": "asha@acme.in",
  "email_verified": true,
  "name": "Asha Rao",
  "preferred_username": "asha"
}

6. Later: who is it now?

curl -H "Authorization: Bearer dk_at_…" https://mail.daakiaa.com/oauth/userinfo

Scopes and claims

Ask only for what you need; people see each item before they allow it. The app's settings say which scopes it may ask for; any other scope you send is left out, and the token answer's scope says what you got.

ScopeClaimsShown to the person as
openidsub (always required)Know who you are on Daakiaa
emailemail, email_verified (always true: it is their Daakiaa mailbox)See your email address
profilename, preferred_usernameSee your name
orgorg_id, org_name, and org_role (admin, hr, accountant or support) only for an admin role over the whole organizationSee your organization and your admin role there
offline_accessa refresh tokenStay signed in when you are not using it

The claims are in the ID token and in userinfo; a claim with no value is left out. email changes if an admin changes the person's address; sub never does, and a later mailbox with an old address gets a new sub.

An access token is for Daakiaa's userinfo only. Do not accept Daakiaa access tokens as sign-ins to your own API: one issued to another app would look the same.

Tokens and lifetimes

WhatLastsNotes
authorization code1 minuteWorks once. A code used twice ends every token it gave.
access token1 hourOpaque (dk_at_…). Send as Authorization: Bearer to userinfo.
ID token1 hourA JWT signed RS256; check it once, at sign-in.
refresh token60 days unused, 1 year at mostOnly with offline_access. A new one comes with each use.
client secretuntil you replace itAfter a new one, the old works 24 hours more (or stops at once if you choose).
signing keyreplaced every 90 daysA new key is in /oauth/jwks an hour before it signs; an old one stays a week. Pick the key by kid and fetch the keys again when a kid is new; never pin one.

Every use of a token checks again that the person's mailbox and organization are active, that their organization allows your app, and that they have not removed it. Changing or resetting the password, turning on 2-step verification, an admin blocking the mailbox or Daakiaa suspending the organization signs the person out of every app.

Staying signed in

Most web apps do not need this: keep your own session, and send the person through Daakiaa again when it ends (it is one click while they are signed in to Daakiaa). If your app works while the person is away, ask for offline_access and keep the refresh token on your server.

curl -u "dk_app_…:dk_secret_…" \
  -d grant_type=refresh_token \
  -d refresh_token=dk_rt_… \
  https://mail.daakiaa.com/oauth/token
  • Each refresh gives a new refresh token; store it and drop the old one. An old refresh token used again means it was copied: Daakiaa then ends the whole sign-in, and the person must sign in again.
  • Refresh one at a time per person (no two requests at once with the same token).
  • You get invalid_grant when the person removed your app, was blocked, changed their password or 2-step verification, or their organization turned your app off. Send them through sign-in again.

Asking again

ParameterEffect
prompt=noneNo screens: back at once with a code, or with error=login_required / consent_required. Compare the sub you get with the person you expect.
prompt=loginThe person must enter their password again, even if signed in (before something sensitive).
prompt=consentShow the "Allow?" screen even if they allowed it before.
prompt=select_accountLet them choose which signed-in Daakiaa account to use.
max_age=<seconds>Their sign-in must be at most this old, or they sign in again. Check auth_time in the ID token.
login_hint=<email>Fills in the address on Daakiaa's sign-in form.

Daakiaa's pages cannot be shown inside a frame, so “silent” sign-in in a hidden iframe does not work; use a refresh token or a normal redirect.

For an organization's own apps, Daakiaa never sends anyone back with an error on its own (anyone can register an app, so that would let a sign-in link send people to any site): the person sees the problem on Daakiaa and goes back with a button. Daakiaa's own apps get their errors straight back.

Phone, desktop and single-page apps

Such apps cannot keep a secret, so they have none: choose Phone, desktop or single-page app when making the app, and send only client_id to the token endpoint. PKCE proves each sign-in. Another program on the device could claim the same scheme or port, so the person sees the “Allow?” screen every time (except with an https return address the app has claimed, such as an Android App Link or iOS Universal Link).

  • Phones: open the sign-in in the system browser (Custom Tabs on Android, ASWebAuthenticationSession on iPhone), never in a WebView. Best, come back on an https address your app has claimed (App Links / Universal Links); otherwise on your own scheme named after your domain, e.g. com.example.erp:/oauth2redirect. The AppAuth libraries do all of this.
  • Desktop: register http://127.0.0.1/callback; any port then works (open a local port at sign-in).
  • Single-page apps: the token and userinfo endpoints answer browser requests from any site (CORS, no cookies). Prefer a small server of your own (a “backend for frontend”) so tokens never sit in the browser.

Code examples

Node.js (openid-client 5)

const { Issuer, generators } = require("openid-client");

let client; // set up once, when the server starts
async function setUp() {
  const daakiaa = await Issuer.discover(process.env.DAAKIAA_ISSUER);
  client = new daakiaa.Client({
    client_id: process.env.DAAKIAA_CLIENT_ID,
    client_secret: process.env.DAAKIAA_CLIENT_SECRET,
    redirect_uris: [process.env.DAAKIAA_REDIRECT_URI],
    response_types: ["code"],
  });
}

// GET /auth/daakiaa
app.get("/auth/daakiaa", (req, res) => {
  const code_verifier = generators.codeVerifier();
  const state = generators.state();
  const nonce = generators.nonce();
  req.session.daakiaa = { code_verifier, state, nonce };
  res.redirect(client.authorizationUrl({
    scope: "openid email profile",
    code_challenge: generators.codeChallenge(code_verifier),
    code_challenge_method: "S256",
    state, nonce,
  }));
});

// GET /auth/daakiaa/callback
app.get("/auth/daakiaa/callback", async (req, res) => {
  const { code_verifier, state, nonce } = req.session.daakiaa ?? {};
  delete req.session.daakiaa; // used once
  // (checks state, the iss parameter, the ID token and its nonce)
  const tokens = await client.callback(process.env.DAAKIAA_REDIRECT_URI,
    client.callbackParams(req), { code_verifier, state, nonce });
  const { sub, email, name } = tokens.claims();
  // find or create the user by sub, then start your own session
});

Next.js (Auth.js)

// auth.ts — return address: https://<your app>/api/auth/callback/daakiaa
import NextAuth from "next-auth";

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [{
    id: "daakiaa",
    name: "Daakiaa",
    type: "oidc",
    issuer: process.env.DAAKIAA_ISSUER,
    clientId: process.env.DAAKIAA_CLIENT_ID,
    clientSecret: process.env.DAAKIAA_CLIENT_SECRET,
    authorization: { params: { scope: "openid email profile" } },
    checks: ["pkce", "state", "nonce"],
  }],
});

Python (Authlib with Flask)

from authlib.integrations.flask_client import OAuth

oauth = OAuth(app)
oauth.register(
    name="daakiaa",
    server_metadata_url=f"{DAAKIAA_ISSUER}/.well-known/openid-configuration",
    client_id=DAAKIAA_CLIENT_ID,
    client_secret=DAAKIAA_CLIENT_SECRET,
    client_kwargs={"scope": "openid email profile", "code_challenge_method": "S256"},
)

@app.route("/auth/daakiaa")
def daakiaa_login():
    return oauth.daakiaa.authorize_redirect(url_for("daakiaa_callback", _external=True))

@app.route("/auth/daakiaa/callback")
def daakiaa_callback():
    if request.args.get("iss") != DAAKIAA_ISSUER:   # Authlib does not check it itself
        abort(400)
    token = oauth.daakiaa.authorize_access_token()   # checks state, nonce and the ID token
    person = token["userinfo"]                       # sub, email, name
    ...

PHP (league/oauth2-client 2.7 or later)

$daakiaa = new \League\OAuth2\Client\Provider\GenericProvider([
    'clientId'                => getenv('DAAKIAA_CLIENT_ID'),
    'clientSecret'            => getenv('DAAKIAA_CLIENT_SECRET'),
    'redirectUri'             => getenv('DAAKIAA_REDIRECT_URI'),
    'urlAuthorize'            => 'https://mail.daakiaa.com/oauth/authorize',
    'urlAccessToken'          => 'https://mail.daakiaa.com/oauth/token',
    'urlResourceOwnerDetails' => 'https://mail.daakiaa.com/oauth/userinfo',
    'scopes'                  => 'openid email profile',
    'scopeSeparator'          => ' ',
    'responseResourceOwnerId' => 'sub',
    'pkceMethod'              => \League\OAuth2\Client\Provider\AbstractProvider::PKCE_METHOD_S256,
]);

// /auth/daakiaa
$url = $daakiaa->getAuthorizationUrl();
$_SESSION['daakiaa_state'] = $daakiaa->getState();
$_SESSION['daakiaa_pkce']  = $daakiaa->getPkceCode();
header('Location: ' . $url);

// /auth/daakiaa/callback
if (!hash_equals($_SESSION['daakiaa_state'] ?? '', $_GET['state'] ?? '')
    || ($_GET['iss'] ?? '') !== 'https://mail.daakiaa.com') {
    exit('Sign-in failed');
}
$daakiaa->setPkceCode($_SESSION['daakiaa_pkce']);
unset($_SESSION['daakiaa_state'], $_SESSION['daakiaa_pkce']);
$token  = $daakiaa->getAccessToken('authorization_code', ['code' => $_GET['code']]);
$person = $daakiaa->getResourceOwner($token)->toArray(); // sub, email, name

Android (AppAuth)

// build.gradle: manifestPlaceholders = [appAuthRedirectScheme: "com.example.erp"]
AuthorizationServiceConfiguration.fetchFromIssuer(Uri.parse(ISSUER)) { config, ex ->
    val request = AuthorizationRequest.Builder(
        config!!, CLIENT_ID, ResponseTypeValues.CODE,
        Uri.parse("com.example.erp:/oauth2redirect"))
        .setScopes("openid", "email", "profile", "offline_access")
        .build()                        // PKCE (S256) is added by AppAuth
    startActivityForResult(authService.getAuthorizationRequestIntent(request), RC_AUTH)
}

The button

Use the Daakiaa mark and the words “Sign in with Daakiaa” (or “Continue with Daakiaa”), on a white or dark button, at least 40 px tall. Do not change the mark's colors or shape.

Sign in with Daakiaa Sign in with Daakiaa
<a href="/auth/daakiaa" class="daakiaa-signin">
  <svg viewBox="0 0 40 40" width="22" height="22" aria-hidden="true" fill="none"
       stroke-linecap="round" stroke-linejoin="round">
    <path d="M10 10.5h17a5 5 0 0 1 5 5v12a5 5 0 0 1-5 5H10a5 5 0 0 1-5-5v-12a5 5 0 0 1 5-5Z"
          stroke="#d91a7a" stroke-width="2.6"/>
    <path d="M8.2 14.2 18.5 22l10.3-7.8" stroke="#d91a7a" stroke-width="2.6"/>
    <circle cx="31.5" cy="10.5" r="7" fill="#fff"/>
    <circle cx="31.5" cy="10.5" r="4.4" fill="#f59e0b"/>
  </svg>
  Sign in with Daakiaa
</a>

<style>
  .daakiaa-signin {
    display: inline-flex; align-items: center; gap: 10px;
    height: 44px; padding: 0 18px; border-radius: 999px;
    border: 1px solid #dadce0; background: #fff; color: #1f1f1f;
    font: 500 15px/1 system-ui, -apple-system, "Segoe UI", sans-serif;
    text-decoration: none;
  }
  .daakiaa-signin:hover { background: #f8f8fa; }
  .daakiaa-signin:focus-visible { outline: 3px solid #d91a7a55; outline-offset: 2px; }
</style>

The mark as a file: daakiaa-mark.svg. Ready buttons: light, dark.

Security checklist

  • Keep the client secret on your server only, and refresh tokens too. Replace the secret at once if it may have leaked (New secret, then Stop old one now).
  • Always send state, nonce and PKCE, and check state and iss when the person comes back (openid-client checks iss; with Authlib, league/oauth2-client or AppAuth compare it yourself).
  • Check the ID token (signature, iss, aud, exp, nonce), or let your library do it. Never accept a token your server did not get from the token endpoint itself.
  • Key your users by sub, not by email.
  • Register only https return addresses you control; never a page that redirects onward. Remove http://localhost ones before going live.
  • Signing out of your app ends your own session. To also end Daakiaa's tokens for your app, call /oauth/revoke with the refresh token.
  • Handle access_denied calmly: the person cancelled, or their organization does not allow your app.

Errors

Back at your return address

errorMeaning
access_deniedThe person cancelled, or may not use your app (their organization's choice, or not one of the organizations it is for).
login_requiredprompt=none, and nobody is signed in (or the sign-in is older than max_age).
consent_requiredprompt=none, and the person has not allowed your app yet.
invalid_scopeA scope your app may not ask for, or openid missing.
invalid_requestSomething missing or wrong, e.g. no PKCE; error_description says what.
unsupported_response_typeOnly response_type=code is supported.

An unknown client ID or a return address the app did not register is never sent back: the person sees the problem on Daakiaa instead.

From the token endpoint

errorHTTPMeaning
invalid_client401Unknown client ID, wrong secret, or a secret sent by an app that has none. Repeated failures from one address wait 15 minutes (429).
invalid_grant400The code or refresh token is wrong, used, run out, for another app or return address, the PKCE verifier does not match, or the person may no longer sign in.
invalid_request400Not a form, a field sent twice, or credentials sent two ways.
unsupported_grant_type400Only authorization_code and refresh_token.

What admins and people control

  • People see every app they signed in to in Daakiaa Mail → Settings → Security, and can remove one; the app is signed out at once.
  • An organization's admin chooses whether its people may sign in to any app, only the organization's own, or none (Admin → Company → Sign-in apps), and sees which apps they use.
  • Changing a password, turning on 2-step verification, or an admin blocking a mailbox signs it out of every app.
  • The organization's rules for where its people may sign in from apply to Sign in with Daakiaa too.