diff --git a/getting-started/authentication.md b/getting-started/authentication.md
index 01fad15..cb3b648 100644
--- a/getting-started/authentication.md
+++ b/getting-started/authentication.md
@@ -27,13 +27,13 @@ To access user data via Verida APIs, you must include a valid `auth_token` in ev
Below is a typical flow when integrating your application with Verida AI:
1. **Generate an authentication request URL**
- * Include the scopes you require as well as the `redirectUrl` for successful authentication.
+ * Include the `scopes` you require as well as the `redirectUrl` for authentication output.
2. **Redirect the user to the authentication request URL**
- * The user is prompted to grant or deny your application access.
+ * The user is prompted to grant or deny your application access via the Verida Vault web application.
3. **User grants access and is redirected back**
* If the user grants access, they are redirected to your specified `redirectUrl` with an `auth_token` in the query parameters.
4. **Store the `auth_token`**
- * Your application should save the token securely, either linked to the user’s account in your database or in the user’s local browser storage.
+ * Your application should save the token securely, either linked to the user’s account in your database or via other usual ways handling auth tokens.
5. **Make requests to Verida APIs**
* Include the token in the `Authorization` header for all subsequent calls to Verida’s APIs.
@@ -41,54 +41,57 @@ Below is a typical flow when integrating your application with Verida AI:
### Generate an Authentication Request URL
-To start the authentication process, build a URL that directs users to Verida’s authentication endpoint. This URL must include several query parameters:
+To start the authentication process, build a URL that directs users to Verida’s authentication page on the Verida Vault web app `https://app.verida.ai/auth`. This URL must include several query parameters:
-* **`redirectUrl`**: The URL in your application that handles a successful user authentication.
* **`scopes`**: An array of scopes that your application requires. The latest valid scopes can be listed via the [Scopes API](https://api.verida.ai/api/rest/v1/auth/scopes).
* **`payer`**: Specifies who will pay for the API requests made with this auth token. Set this to either `user` or `app`.
+* **`appDID`**: Your application Verida DID is required to identify your application.
+* **`redirectUrl`**: The URL in your application that handles a successful user authentication.
+* **`state`**: Optionally a state object (stringified) for your own reference (User ID, etc.). The state will not be altered and will be returned to the `redirectUrl` as part of the response.
Below is an example authentication request URL (URL-encoded) that includes three scopes:
```
-https://api.verida.ai/api/rest/v1/auth/auth?scopes=api%3Ads-query&scopes=api%3Allm-agent-prompt&scopes=api%3Allm-profile-prompt&redirectUrl=http%3A%2F%2Flocalhost%3A8080%2F
+https://app.verida.ai/auth?scopes=api%3Ads-query&scopes=api%3Allm-agent-prompt&scopes=api%3Allm-profile-prompt&redirectUrl=http%3A%2F%2Flocalhost%3A8080%2F&appDID=did%3Avda%3Amainnet%3A0x8013f9A...086
```
#### TypeScript Example
```ts
// Build authentication URL
-const AUTH_ENDPOINT = "https://api.verida.ai/api/rest/v1/auth/auth";
-const authLink = new URL(AUTH_ENDPOINT);
+const authLink = new URL("https://app.verida.ai/auth");
// Add scopes
authLink.searchParams.append("scopes", "api:ds-query");
authLink.searchParams.append("scopes", "api:llm-agent-prompt");
-// Add your application URL
-authLink.searchParams.append("redirectUrl", "https://yourapplication.com/auth-success");
-
// Application will pay for API requests
authLink.searchParams.append("payer", "app");
+// Your Verida DID identifying your application
+authLink.searchParams.append("appDID", "did:vda:mainnet:0x8013f9A...086");
+
+// Add your application URL to handle the response
+authLink.searchParams.append("redirectUrl", "https://yourapplication.com/auth-callback");
+
+// An optional state object
+authLink.searchParams.append("state", JSON.stringify({ userId: "123" }));
+
// Redirect user to start the authorization process
window.location.href = authLink.toString();
```
***
-### Display the Verida Connect Button
+### Guidelines on displaying Verida Connect to your users
-Instead of automatically redirecting, you can provide a **Connect** button in your UI. When clicked, it sends users to the Verida authentication flow.
+Similar to a standard OAuth mechanism, provide users with a button to explicitly click to intiate the authentication with Verida. The button would direct the user to the Authentication Request URL generated in the previous step.
-
+The button should include a [Verida logo](https://community.verida.network/verida-overview/brand-assets#download-the-brand-asset-pack) and the label "Connect Verida". The logo, label and color scheme must follow Verida's [branding guidelines](https://community.verida.network/verida-overview/brand-assets).
-```html
-
-
-
-```
+
-Replace `${authLink}` with the URL generated in the previous step.
+In addition to the button, consider explaining to your users the reasons your application needs Verida and how their personal data will be used.
***
@@ -96,21 +99,29 @@ Replace `${authLink}` with the URL generated in the previous step.
Once the user grants your application access, they will be redirected to the `redirectUrl` you specified with an `auth_token` query parameter.
-Example of how to capture the `auth_token` in TypeScript:
+If you passed a `state` in the request, it will be returned with response (successfull or not).
+
+In the case of a non-successful authentication, the redirect URL will contains an `error` and `error_description` query parameters. The values for the `error` parameter are: `access_denied`, `invalid_request` and `server_error`.
+
+TypeScript example of how to capture the `auth_token` and other response elements:
```ts
const currentUrl = new URL(window.location.href);
+
const authToken = currentUrl.searchParams.get("auth_token");
+const state = currentUrl.searchParams.get("state");
+const error = currentUrl.searchParams.get("error");
if (authToken) {
- // Save the token, e.g. in localStorage or your application database
- localStorage.setItem("veridaAuthToken", authToken);
-
- // You can now use this token to make requests to Verida APIs
+ // Save the token securely
+ // ...
+ // You can now use this token to make requests to Verida APIs
}
-```
-***
+if (error) {
+ // Handle the failure of the authentication
+}
+```
***
@@ -118,4 +129,4 @@ if (authToken) {
* **Explore Additional Scopes**: Visit [Verida’s Scopes API](https://api.verida.ai/api/rest/v1/auth/scopes) for a comprehensive list of available scopes.
* **Advanced Use Cases**: Consider reading more about Verida’s data storage, encryption, and decentralized identity solutions to fully leverage the ecosystem.
-* **Production Deployment**: If you’re planning a production rollout, ensure you use secure storage for the `auth_token`.
+* **Production Deployment**: If you’re planning a production rollout, ensure you use secure storage for the `auth_token` (https-only cookie, your backend database, etc.).
