Superface provides a user interface that allows users to securely configure the accounts they will use with any of the tools you are providing via your agent.
In order to manage this, we handle sessions in a way that allows users access to their configuration at any time, whilst providing your agent with the correct prompts to help the user get set up.
In order to ensure that your users are able to access their tool configuration at any time, and to ensure Superface is able to identify which of your users is which you must create a unique ID for each user.
This ID is used when creating a session via the /session endpoint, and also when calling the /perform endpoint to execute a particular function on behalf of a user.
How you format the unique ID for your users is up to you as long as the same ID is always used to identify a particular user. You may already have a unique IDs assigned to your users and you are welcome to use them with Superface as well.
For example, an alphanumeric string such as youragentname|unique_user_id would be sufficient.
<aside> <img src="/icons/light-bulb_gray.svg" alt="/icons/light-bulb_gray.svg" width="40px" />
STORE THE UNIQUE ID
Remember to store the unique ID as part of your user's profile. Superface's API will need it to continue to identify their tool configurations.
</aside>
To create a new session via the API, use the /session endpoint making sure to include the x-superface-user-id header, with your user's unique ID as the value.
Depending on the purpose of your agent you can choose when to create a session for a user, but it needs to be done at the point you require a user to configure their access to a tool (or tools), or if you want to provide them with a URL to modify or revoke access.
curl -X POST \\
-H "Content-Type: application/json" \\
-H "Authorization: Bearer <auth_token>" \\
-H "x-superface-user-id: <your_agent_name|unique_user_id>" \\
<https://pod.superface.ai/api/hub/session>
The response to this request will look similar to this:
{
"status": "success",
"configuration_url": "<https://pod.superface.ai/api/hub/session/psxis99ux9>",
"assistant_hint": "Tell user to go to URL at 'configuration_url' to configure to open configuration. Always show the whole URL to the user. The 'configuration_url' expires in 15 minutes."
}
The configuration_url is provided by Superface and allows the user to securely authenticate their own credentials for any of the tools you have made available.
An assistant_hint is provided as a helper for your agent so that it can understand the context of the response to this request.
The configuration_url will expire after 15 minutes. However, as long as x-superface-user-id is included in the headers of your request to /session a new URL can be generated that will allow the user to access to their tool authentications at any time.