Skip to content

Direct access (SSO) ​

Integrate with an AI assistant
Download or copy the integration prompt for Direct access (SSO) and paste it into Claude Code, Cursor or Copilot: it contains auth, end-to-end examples and a checklist.
Open

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 ​

  1. The user clicks "Go to Dokicasa" on your site.
  2. Your server calls Dokicasa with your API key and the user's email.
  3. Dokicasa finds the user among yours, or creates them, and returns a login link valid for 5 minutes that can be used only once.
  4. 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.

bash
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"
  }'
json
{
  "login_url": "https://app.dokicasa.it/redirect-sso?code=Xk2...",
  "expires_in": 300,
  "user_id": 48213,
  "created": true
}
FieldRequiredDescription
emailyesThe user's email. If there is no external_user_id already linked, it identifies the user
external_user_idrecommendedThe 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_idnoThe id of the group, agency or branch in your system. We store it to recognise users of the same group
first_namenoFirst name. Only used when the user is created
last_namenoLast name. As above
company_namenoCompany name. As above
vat_codenoItalian VAT number (11 digits). Ignored if invalid. As above
phonenoPhone. As above
professional_typenoAZIENDA (default), PROFESSIONISTA or PRIVATO. As above
redirect_pathnoLanding page after login: a Dokicasa path starting with /, for example /servizi/registrazione-contratto-locazione/richiedi. Default: the private area
redirect_urlnoInstead 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.

php
// 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'));
js
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.

  1. In WordPress go to Plugins → Add New → Upload Plugin, choose the zip and activate it.

  2. 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.

  3. 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:

AttributeDefaultDescription
testothe one in the settingsButton text
paginathe one in the settingsThe Dokicasa page the user lands on
classebutton dokicasa-ssoCSS 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.

  • 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 ​

StatuscodeMeaning
401Missing or invalid API key
403Direct access not enabled on your account, or call from an IP you have not listed
409EMAIL_NOT_YOURSThe 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
409USER_DISABLEDThe user has been disabled
422Invalid data, for example a wrong email or a redirect_path that does not start with /