Authentication service

A REST API towards the authentication features of the Pointsharp ID.

API Description

POST an

Performs an authentication request for a user based on the given data.

DELETE Authentication/Cache?Method={Method}&CacheTime={CacheTime}&Username={Username}&UserStorageName={UserStorageName}

Removes the authentication cache specified by the request.

GET Authentication/Cache?Method={Method}&CacheTime={CacheTime}&Username={Username}&UserStorageName={UserStorageName}

Retrieves the authentication cache for a specific user.

Examples

The authentication service enables performing authentication requests towards a Pointsharp ID from any service calling it. Here follows some example code that interacts with the authentication services.

C#

Here follows example code to interact with the web API authentication services using C#.

C# authentication 
using PointSharp.WebServices.Models.Authentication;
using System;
using System.Net.Http;
using System.Threading.Tasks;

namespace PointSharp.WebServices.Examples
{
    class Program
    {
        static void Main(string[] args)
        {
            var request = new AuthenticationRequest()
            {
                Username = "TestUser",
                Password = "1234",
                Method = "PointSharp Password"
            };

            // Call the Authentication method.
            var task = Authenticate(@"http://localhost/api/an/", request);
            task.Wait();

            if (task.Result)
            {
                // Authentication Successful
                Console.WriteLine("The authentication was successful");
            }
            else
            {
                // Authentication Failed
                Console.WriteLine("The authentication failed");
            }

            Console.ReadLine();
        }

        private static async Task Authenticate(string url, AuthenticationRequest request)
        {
            try
            {
                using (var client = new HttpClient())
                {
                    // NOTE: Extension method PostAsJsonAsync(...) requires
                    // System.Net.Http.Formatting.dll and Newtonsoft.Json.dll v 4.5.0.0
                    var response = await client.PostAsJsonAsync(url, request);
                    string message;

                    if (response.IsSuccessStatusCode)
                    {
                        // Get response data
                        var reply = await response.Content.ReadAsAsync();
                        message = string.Format("Authentication reply message: {0}", reply.Message);

                        // Verify accept code (ACCEPT = 1)
                        return reply.Code == 1;
                    }
                    else
                    {
                        message = string.Format("API Responded with HTTP {0}", response.StatusCode);
                    }

                    // Log message
                    Console.WriteLine(message);
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e.ToString());
            }
            return false;
        }
    }
}

HTML with JavaScript

Here follows example code to interact with the web API authentication services from a HTML page using JavaScript.

JavaScript authentication 
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>Authentication Sample</title>
</head>
<body>

<div>
<h2>Authentication Sample</h2>
</div>
<table>
    <tr>
        <td>Username:</td>
        <td><input type="text" id="username" /></td>
    </tr>
    <tr>
        <td>Password:</td>
        <td><input type="password" id="password" /></td>
    </tr>
    <tr>
        <td>Method:</td>
        <td><input type="text" id="method" /></td>
    </tr>
    <tr>
        <td></td>
        <td><input type="button" value="Authenticate" onclick="authenticate();" /></td>
    </tr>
</table>

<p id="msg" />

<script src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-2.0.3.min.js"></script>
<script>
    var uri = "http://localhost/api/an/";

    function authenticate() {
        var AuthenticationRequest = { Username: $('#username').val(), Password: $('#password').val(), Method: $('#method').val()};
        $.ajax({
            type: "POST",
            url: uri,
            data: JSON.stringify(AuthenticationRequest),
            contentType: "application/json; charset=utf-8",
            dataType: "json"
        })
            .done(function (data) {
                if(data.Code == 1)
                    $('#msg').text("Authentication Accept!");
                else if(data.Code == 2)
                    $('#msg').text("Authentication Challenge!");
                else if(data.Code == 3)
                    $('#msg').text("Authentication Reject Challenge!");
                else if(data.Code == 4)
                    $('#msg').text("Authentication Reject!");
                else if(data.Code == 5)
                    $('#msg').text("Authentication Error!");
                else
                    $('#msg').text("Authentication code not implemented!");
            })
            .fail(function (jqXHR, textStatus, err) {
                $('#msg').text('Error: ' + err);
            });
    }
</script>
</body>
</html>

Response Codes

Any authentication request will return an HTTP 200 OK in the response header as long as the request data was in correct format and no server side related issues was enforced. However, the authentication itself is evaluated separately, and its result is seen in the authentication reply code, Code. See the authentication event code, EventCode, for details of what event that was triggered when executing the request.

Authentication Reply Codes

A Pointsharp ID authentication reply code is a constant decimal value representing the state of the authentication.

Name Description

ACCEPT

Code: 1. The user is authenticated.

CHALLENGE

Code: 2. The user needs to provide further credentials, such as a One-Time Password. Check the reply message for more information. This reply also contains a session id used for stateful authentication.

REJECT_CHALLENGE

Code: 3. The user needs to provide further credentials, such as a One-Time Password. Check the reply message for more information. This reply holds no session id, i.e. stateless authentication.

REJECT

Code: 4. The user is not authenticated. Check the reply message for more information.

ERROR

Code: 5. An error occurred when trying to authenticate the user. Should be combined with an event code describing the issue

Authentication Event Codes

A Pointsharp ID authentication event code is a constant hexadecimal value describing a type of event executed during an authentication. An authentication event describes what caused the authentication to pass or fail.

Name Code (Hex) Code (Dec)

NONE

0x00000000

0

AUTHN_INVALID_LICENSE

0x1000

4096

AUTHN_LICENSE_LIMIT

0x1001

4097

AUTHN_NO_USERNAME

0x2100

8448

AUTHN_NO_USER_STORAGE

0x2101

8449

AUTHN_UNKNOWN_USER

0x2102

8450

AUTHN_USER_LOCKED

0x2103

8451

AUTHN_USER_TIME_LOCKED

0x2104

8452

AUTHN_USER_DISABLED

0x2105

8453

AUTHN_NO_DEVICE

0x2106

8454

AUTHN_EMPTY_PASSWORD

0x2107

8455

AUTHN_NO_POINTSHARP_PASSWORD

0x2108

8456

AUTHN_PLUGIN

0x2109

8457

AUTHN_USER_MISSING_ATTRIBUTE

0x2110

8464

AUTHN_NOTIFICATION_FAILED

0x2111

8465

AUTHN_UNKNOWN_METHOD

0x2300

8960

AUTHN_SMARTAUTH_REJECT

0x2301

8961

AUTHN_SMARTAUTH_ERROR

0x2302

8962

AUTHN_SMARTAUTH_UNKNOWN_METHOD

0x2303

8963

AUTHN_CACHE_ACCEPT

0x2304

8964

AUTHN_CACHE_EXPIRED

0x2305

8965

AUTHN_CACHE_LASTFAILED

0x2306

8966

AUTHN_SERVER_ERROR

0x2307

8967

AUTHN_ACCEPT

0x2500

9472

AUTHN_ACCEPT_PASSWORD_CHANGE

0x2501

9473

AUTHN_REJECT_WRONG_PASSWORD

0x2502

9474

AUTHN_REJECT_WRONG_OTP

0x2503

9475

AUTHN_REJECT_TOKEN_DISABLED

0x2504

9476

AUTHN_REJECT_NO_TOKEN

0x2505

9477

AUTHN_CHALLENGE

0x2506

9478

AUTHN_CHALLENGE_RETRY

0x2507

9479

AUTHN_PASSWORD_MUST_CHANGE

0x2508

9480

AUTHN_PASSWORD_CHANGE_CHALLENGE

0x2509

9481

AUTHN_PASSWORD_CHANGE_FAILED

0x2510

9488

AUTHN_LOGIN

0x2511

9489

AUTHN_LOGIN_MULTIPLE_SESSION_FOUND

0x2512

9490

AUTHN_LOGIN_CHALLENGE

0x2513

9491

PASSWORD_RESET_ACCEPT

0x2700

9984

PASSWORD_RESET_SESSION_THROTTLE

0x2701

9985

PASSWORD_RESET_BLOCK_USER_STORAGE_PWD

0x2702

9986

PASSWORD_RESET_DISABLED

0x2703

9987

POST an

Performs an authentication request for a user based on the given data.

Request information

Parameters

Name Description Additional information

request

The request data to be used for authenticating a user.

Define this parameter in the request body.

Parameter information

request

Authentication request with parameters to be used for authentication with Pointsharp ID.

Property Description Additional information

ClientIp (String)

Client information, IP address.

This parameter is optional.

Method (String)

The method to authenticate with.

This parameter is optional.

Password (String)

The password to authenticate with.

This parameter is required.

Properties (AuthenticationProperty[])

The authentication properties.

This parameter is optional.

SessionId (String)

The session id to authenticate with. It is used when authenticating with challenge.

This parameter is optional.

TransactionId (String)

Transaction via trace.

This parameter is optional.

Username (String)

The name of the user.

This parameter is required.

UserStorageName (String)

The name of the storage where the user resides. If this value is NULL (not set) then Pointsharp ID tries to find the unique user by searching through all configured user storages.

This parameter is optional.

Request body formats

application/json, text/json 
{
  "Password": "sample string 1",
  "Method": "sample string 2",
  "SessionId": "sample string 3",
  "ClientIp": "sample string 4",
  "Properties": {
    "$type": "PointSharp.WebServices.Models.Authentication.AuthenticationProperty[], PointSharp.WebServices.Models",
    "$values": [
      {
        "$type": "PointSharp.WebServices.Models.Authentication.AuthenticationProperty, PointSharp.WebServices.Models",
        "Key": "sample string 1",
        "Value": {
          "$type": "System.Byte[], mscorlib",
          "$value": "QEA="
        }
      },
      {
        "$type": "PointSharp.WebServices.Models.Authentication.AuthenticationProperty, PointSharp.WebServices.Models",
        "Key": "sample string 1",
        "Value": {
          "$type": "System.Byte[], mscorlib",
          "$value": "QEA="
        }
      }
    ]
  },
  "TransactionId": "sample string 5",
  "Username": "sample string 6",
  "UserStorageName": "sample string 7"
}
application/xml, text/xml 
<AuthenticationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Username>sample string 6</Username>
  <UserStorageName>sample string 7</UserStorageName>
  <Password>sample string 1</Password>
  <Method>sample string 2</Method>
  <SessionId>sample string 3</SessionId>
  <ClientIp>sample string 4</ClientIp>
  <Properties>
    <AuthenticationProperty>
      <Key>sample string 1</Key>
      <Value>QEA=</Value>
    </AuthenticationProperty>
    <AuthenticationProperty>
      <Key>sample string 1</Key>
      <Value>QEA=</Value>
    </AuthenticationProperty>
  </Properties>
  <TransactionId>sample string 5</TransactionId>
</AuthenticationRequest>

Response information

A reply containing information about the authentication, such as the reply code and the required data if the user is authenticated.

Response body formats

application/json, text/json 
{
  "Code": 1,
  "EventCode": 2,
  "Message": "sample string 3",
  "Method": "sample string 4",
  "SessionId": "sample string 5",
  "Username": "sample string 6",
  "Properties": {
    "$type": "System.Collections.Generic.List`1[[PointSharp.WebServices.Models.Authentication.AuthenticationProperty, PointSharp.WebServices.Models]], mscorlib",
    "$values": [
      {
        "$type": "PointSharp.WebServices.Models.Authentication.AuthenticationProperty, PointSharp.WebServices.Models",
        "Key": "sample string 1",
        "Value": {
          "$type": "System.Byte[], mscorlib",
          "$value": "QEA="
        }
      },
      {
        "$type": "PointSharp.WebServices.Models.Authentication.AuthenticationProperty, PointSharp.WebServices.Models",
        "Key": "sample string 1",
        "Value": {
          "$type": "System.Byte[], mscorlib",
          "$value": "QEA="
        }
      }
    ]
  }
}
application/xml, text/xml 
<AuthenticationReply xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Code>1</Code>
  <EventCode>2</EventCode>
  <Message>sample string 3</Message>
  <Method>sample string 4</Method>
  <SessionId>sample string 5</SessionId>
  <Username>sample string 6</Username>
  <Properties>
    <AuthenticationProperty>
      <Key>sample string 1</Key>
      <Value>QEA=</Value>
    </AuthenticationProperty>
    <AuthenticationProperty>
      <Key>sample string 1</Key>
      <Value>QEA=</Value>
    </AuthenticationProperty>
  </Properties>
</AuthenticationReply>

DELETE Authentication/Cache?Method={Method}&CacheTime={CacheTime}&Username={Username}&UserStorageName={UserStorageName}

Removes the authentication cache specified by the request.

Request information

Parameters

Name Description Additional information

request

The request specifying the cache to delete.

Define this parameter in the request URI.

Parameter information

request

Contains data required to request authentication cache for a specific user.

Property Description Additional information

CacheTime (DateTime)

The point in time when the cache to was created.

This parameter is optional.

Method (String)

The authentication method specifying the cache.

This parameter is optional.

Username (String)

The name of the user.

This parameter is required.

UserStorageName (String)

The name of the storage where the user resides. If this value is NULL (not set) then Pointsharp ID tries to find the unique user by searching through all configured user storages.

This parameter is optional.

GET Authentication/Cache?Method={Method}&CacheTime={CacheTime}&Username={Username}&UserStorageName={UserStorageName}

Retrieves the authentication cache for a specific user.

Request information

Parameters

Name Description Additional information

request

The request specifying the cache to retrieve.

Define this parameter in the request URI.

Parameter information

request

Contains data required to request authentication cache for a specific user.

Property Description Additional information

CacheTime (DateTime)

The point in time when the cache to was created.

This parameter is optional.

Method (String)

The authentication method specifying the cache.

This parameter is optional.

Username (String)

The name of the user.

This parameter is required.

UserStorageName (String)

The name of the storage where the user resides. If this value is NULL (not set) then Pointsharp ID tries to find the unique user by searching through all configured user storages.

This parameter is optional.

Response information

The list of requested authentication caches.

Response body formats

application/json, text/json 
[
  {
    "$type": "PointSharp.WebServices.Models.User.AuthenticationCache, PointSharp.WebServices.Models",
    "Method": "sample string 1",
    "CacheTime": "2025-09-04T13:37:49.3548612+02:00",
    "Counter": 3
  },
  {
    "$type": "PointSharp.WebServices.Models.User.AuthenticationCache, PointSharp.WebServices.Models",
    "Method": "sample string 1",
    "CacheTime": "2025-09-04T13:37:49.3548612+02:00",
    "Counter": 3
  }
]
application/xml, text/xml 
<ArrayOfAuthenticationCache xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <AuthenticationCache>
    <Method>sample string 1</Method>
    <CacheTime>2025-09-04T13:37:49.3548612+02:00</CacheTime>
    <Counter>3</Counter>
  </AuthenticationCache>
  <AuthenticationCache>
    <Method>sample string 1</Method>
    <CacheTime>2025-09-04T13:37:49.3548612+02:00</CacheTime>
    <Counter>3</Counter>
  </AuthenticationCache>
</ArrayOfAuthenticationCache>