Overview

Sometimes you may not need documents signed, approved, or delivered through the AlphaTrust system but still want to leverage AlphaTrust's robust authentication options, such as registered user, One-Time Password (OTP) via SMS, phone, or email, KBA, etc. for your own application. All of these options can even be combined as a two factor authentication option. The Authentication Only feature enables this by allowing you to securely authenticate users and redirect them to your application without involving document workflows.

Setting Up Authentication Only

To configure an authentication-only transaction, use the CreateTransactions() method as follows:

1. Call the API: Send a POST request to the endpoint {{RestBaseUrl}}/api/v5/transactions/create.
2. Configure the Payload:
   • Do not populate the .Documents field (set it to null or omit it).
   • Set the .IsAuthenticationOnly property to true.
   • Define the Participants array as you normally would for a signing transaction, including each participant's Authentication object with their desired authentication method (e.g., "Type": "Password"). The only difference is there are not .Tasks property to define there.
   • Set a required Description property in a way that will help you search for this in the status reports.
   • Optionally, include the SessionExpirationMinutes property to determine how long the security token lasts.
   • Add "ResponseIncludes": { "IncludeParticipants": true } to ensure participant details, including URLs, are returned in the response.
3. Send the Request: Submit the payload to the API.
4. Retrieve Participant URLs: The response will include unique participant URLs, which you can send to users (e.g., via email or redirection) for authentication.

Once users access these URLs, they authenticate using the specified method(s), and upon success, they are redirected to your application with a security token in the URL.

Example

Here’s a sample JSON payload for an authentication-only transaction:

{
    "Transactions": [
        {
            "IsAuthenticationOnly": true,
            "ProntoID": "{{ApiKey}}",
            "SessionExpirationMinutes": 5,
            "Description": "My Test Authentication Transaction",
            "Participants": [
                {
                    "FullName": "John Q. Tester",
                    "Authentication": {
                        "Type": "Password",
                        "Data": "1234"
                    },
                    "SendRequestViaEmail": true,
                    "EmailAddress": "john.tester@somedomain.com"
                }
            ]
        }
    ],
    "ResponseIncludes": {
        "IncludeParticipants": true
    }
}

Full C# example:

var t = new TransactionCreateModel();
t.Description = "My Authentication Only Transaction";
t.ProntoID = "Default";
t.SessionExpirationMinutes = 5

var participant = new ParticipantInsertModel();
participant.IsAuthenticationOnly = true;
participant.FullName = "John Smith";
participant.EmailAddress = "testing@alphatrust.com";
participant.SendRequestViaEmail = true;
participant.ClientReturnUrl = "https://mydomain.com/private-endpoint-that-requires-authentication"

// if you have more than one Participant, you can add them all into the array here
t.Participants = new List<object> { participant };

// The values below will vary for your server's configuration
var apiKey = "MyCompanyInc";
var apiSecret = "4dda426f-134f-4a55-9dff-40f4c227e1a0";
var apiUsername = "my-api-user";
var apiPassword = "17334bae-5eff-4ee1-9a96-fa5dde6cbfc9";

var transactionList = new List<object> { t };

// If you need additional properties returned (i.e. ParticipantID or signing URL),
// you can define those to be included in the response as well here:
var includes = new TransactionIncludesModel()
                        {
                            IncludeParticipants = true,
                        }

var req = new TransactionCreateRequestModel();
req.EnableLogging = true;
req.ResponseIncludes = includes
req.Transactions = transactionList;

var myRestEndpointUrl = "https://my-esign-domain.com/rest";
var api = new TransactionsApi(myRestEndpointUrl);
var results = await api.CreateTransactionsAsync(req, apiKey, apiSecret, apiUsername, apiPassword);

if (results.IsSuccessful.Value)
{
    // do work...
}
else
{
    // handle error
}

Explanation

• IsAuthenticationOnly: true: Indicates this transaction is for authentication only, bypassing document processes.
• ProntoID: Your Group ID (usually your ApiKey value) for authentication with AlphaTrust.
• SessionExpirationMinutes: 5: Sets a 5-minute session timeout.
• Participants: Defines a single participant, "John Q. Tester," using password authentication with a PIN of "1234".
  • The SendRequestViaEmail flag triggers an email with the authentication URL.
  • The ClientReturnUrl would be essential in this scenario since you need to tell the system to send the participant to your application using this property.
• ResponseIncludes: Ensures the response includes participant URLs.

Handling the Authentication Flow

1. User Authentication: The participant accesses their URL (normally used for signing documents) and authenticates using the configured method (e.g., entering "1234" as a password).
2. Redirection: After successful authentication, AlphaTrust redirects the user to the ClientReturnUrl in your application.
3. Security Token: The redirect includes a short-lived security token as a query parameter, e.g., https://yourapp.com/auth?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....

Validating the Security Token

When the user arrives at your site, you can use the short-lived security token to:

• Validate Authenticity: Confirm the token’s integrity and origin (e.g., verify the JWT signature with AlphaTrust’s public key, available via the API or account settings).
• Identify the User: Extract claims like user ID, name, or email from the security token's response.
• Determine Next Steps: Use the token data to decide what the user should do next in your system (e.g., grant access to specific resources).