Direct access (SSO)
With direct access your users enter Dokicasa from your website, without a password. A "Go to Dokicasa" button in your software takes them straight into their private area, or directly to a practice.
Activation on request
Direct access must be enabled by Dokicasa on your account. Also send us the public IPs of your servers: they are not mandatory, but if you provide them, calls from other IPs are rejected.
How it works
- The user clicks "Go to Dokicasa" on your site.
- Your server calls Dokicasa with your API key and the user's email.
- Dokicasa finds the user among yours, or creates them, and returns a login link valid for 5 minutes that can be used only once.
- Your server redirects the user's browser to that link: the user is in.
The user becomes a user linked to your account, like the ones you register yourself: they inherit your conditions and you see their practices.
Do not call the endpoint from the browser
The call uses your API key, which must never reach the page. Call it from your server when the user clicks, then redirect.
The call
curl -X POST https://app.dokicasa.it/api/v3/sso/login-link \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"email": "mario.rossi@example.com",
"first_name": "Mario",
"last_name": "Rossi",
"redirect_path": "/app/area-personale/home"
}'{
"login_url": "https://app.dokicasa.it/redirect-sso?code=Xk2...",
"expires_in": 300,
"user_id": 48213,
"created": true
}| Field | Required | Description |
|---|---|---|
email | yes | The user's email. If there is no external_user_id already linked, it identifies the user |
external_user_id | recommended | The user's id in your system. We link it to the Dokicasa user: if the email changes later, the user stays the same |
external_group_id | no | The id of the group, agency or branch in your system. We store it to recognise users of the same group |
first_name | no | First name. Only used when the user is created |
last_name | no | Last name. As above |
company_name | no | Company name. As above |
vat_code | no | Italian VAT number (11 digits). Ignored if invalid. As above |
phone | no | Phone. As above |
professional_type | no | AZIENDA (default), PROFESSIONISTA or PRIVATO. As above |
redirect_path | no | Landing page after login: a Dokicasa path starting with /, for example /servizi/registrazione-contratto-locazione/richiedi. Default: the private area |
redirect_url | no | Instead of redirect_path: the full address, only on app.dokicasa.it |
Personal data is only used on creation: we do not overwrite it for an existing user.
In the response, created is true when the user has just been created (201 response) and false when they already existed (200 response). Keep user_id if you want to link it to your data.
// In the controller of the "Go to Dokicasa" button
$res = Http::withToken(env('DOKICASA_API_KEY'))
->acceptJson()
->post('https://app.dokicasa.it/api/v3/sso/login-link', [
'email' => $user->email,
'first_name' => $user->first_name,
'last_name' => $user->last_name,
]);
return redirect()->away($res->json('login_url'));app.get('/go-to-dokicasa', async (req, res) => {
const r = await fetch('https://app.dokicasa.it/api/v3/sso/login-link', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.DOKICASA_API_KEY}`,
Accept: 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify({ email: req.user.email, first_name: req.user.firstName }),
})
const { login_url } = await r.json()
res.redirect(login_url)
})A button on your site
The "Go to Dokicasa" or "Buy here" button cannot be a fixed link: anyone who copied it would get into the account. It must point to a page on your site that, on click, makes the call above for the logged-in user and then redirects the browser to login_url.
So it only works for users logged in to your site. For anonymous visitors use a plain link to https://app.dokicasa.it: they sign up or log in there.
WordPress site
We prepared a plugin that does all this: download dokicasa-sso.zip.
In WordPress go to Plugins → Add New → Upload Plugin, choose the zip and activate it.
Go to Settings → Dokicasa, paste your API key and save. There you also choose the environment (production or test), the button text and the landing page.
Put the shortcode where you want the button, in a page, a widget or the menu:
text[dokicasa_sso] [dokicasa_sso testo="Buy here" pagina="/servizi/registrazione-contratto-locazione/richiedi"]
No code to write. The key stays on the WordPress server and is never shown, not even in the settings. If you prefer, you can put it in wp-config.php with define('DOKICASA_API_KEY', '...');: in that case that one is used.
The shortcode attributes, all optional, change a single button:
| Attribute | Default | Description |
|---|---|---|
testo | the one in the settings | Button text |
pagina | the one in the settings | The Dokicasa page the user lands on |
classe | button dokicasa-sso | CSS classes, to use your theme's button style |
The plugin sends Dokicasa the WordPress user's email, first and last name and their id as external_user_id. Users not logged in to WordPress are sent to your site's login first.
The login link
- It lasts 5 minutes and works only once: request a new one on every click, do not store it and do not send it by email.
- Opened a second time, or after it expires, it returns
410. - After logging in, the user stays logged in to Dokicasa as with a normal login.
Staging
To test without touching production use https://testing.dokicasa.it: same call (/api/v3/sso/login-link), with the staging API key. Ask Dokicasa to enable SSO there too.
With the WordPress plugin choose Prova (testing.dokicasa.it) in Settings → Dokicasa and paste the staging API key.
Errors
| Status | code | Meaning |
|---|---|---|
401 | Missing or invalid API key | |
403 | Direct access not enabled on your account, or call from an IP you have not listed | |
409 | EMAIL_NOT_YOURS | The email is already registered on Dokicasa but is not one of your users. For security we never enter other people's accounts: the user logs in with their own credentials |
409 | USER_DISABLED | The user has been disabled |
422 | Invalid data, for example a wrong email or a redirect_path that does not start with / |