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
- 1Make 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).
- 2Keep 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
- 3Set 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.
- 4Add the button
A “Sign in with Daakiaa” button on your sign-in page that starts the flow (design).
- 5Use 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.
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.
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
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_grantwhen 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
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, nameAndroid (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)
}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,nonceand PKCE, and checkstateandisswhen the person comes back (openid-client checksiss; 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://localhostones before going live. - Signing out of your app ends your own session. To also end Daakiaa's tokens for your app, call
/oauth/revokewith the refresh token. - Handle
access_deniedcalmly: the person cancelled, or their organization does not allow your app.
Errors
Back at your return address
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
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.