API Quickstart¶

This section will be a quickstart guide to using the Allthenticate API.

API Key¶

Obtain an API Key from the admin portal if you don’t already have one. This is required to make API calls.

This can be done by visiting the admin portal -> Settings -> API Keys -> Generate a new key

You can set a custom expiry time for the key if you wish, or leave it at 0 to never expire.

You will need to add this key in your Web Request s in order to make API calls.

Retrieve all Users¶

To retrieve all users in your organization, make a GET request to the /multipleusers endpoint.

email:

(Optional) Boolean flag if you want the email of each user included in the name field.

user_tag:

(Optional) Use GUEST to get the guest users

return:

[
    {
        "ad_status": "ACTIVE", # Authentication Device Status
        "active_date": "2020-03-20 01:30:34",
        "confirmed": "2020-03-20 01:30:16",
        "created": "2020-03-20 01:30:05",
        "device_added": "2023-01-23 23:46:35",
        "email": "joe@developer.com",
        "email_id": 1,
        "email_status": "CONFIRMED",
        "first_name": "Chad",
        "groups": [ [ "Employees" ], ...],
        "last_name": "Spensky",
        "name": "Joe Developer"
        "user_id": 1,
        "username": "cspensky",
        "unique_id": Unique identifier
        "name": first_name + last_name
    },
    <more users>
]

The response will contain a list of all users in your organization.

Invite Users¶

In order to use Allthenticate, you will need to invite users to your organization.
To make the API call, do the following:
Make a POST request to the /invites endpoint with the following parameters:
emails:

(Required) List of email addresses to invite to the organization

smartcards:

(Optional) List of smartcard arrays mapped directly to the emails in the same order

groups:

(Optional) List of group objects that should contain the properties ‘id’ and ‘name’,

no_email:

(Optional) If this is set to ‘true’ no emails will be sent to the invited users

which each invited user will be added to
return:
{
    "success": "Success! All members have been invited to join your organization.",
    "added": added,
    "invited": invited,
    "exists": exists,
    "invalid": invalid,
    "failed_invite": failed_invited,
    "add_ids": add_ids,
    "group_names": group_names,
    "send_email": send_email,
}, 200
{"error": "error message"}, [400 or 500] on failure
The user will receive an email with a link to create an account and set their password.

Managing Groups¶

You can create groups and include users for efficient management.
To make a new group, do the following:
Make a POST request to the /groups endpoint with the following eters:
type:

(Required) The type of group to create. Either “users” or “resources”

name:

(Required) The name of the group to create

add_ids:

(Required) A list of IDs to add to the group. For users ids are from the email_id returned in a get request to the user endpoint. For resources ids are from the resource_id returned in a get request to the resource endpoint. Formatted as [1, 2,…]

resource_type:

(Optional) The type of resource to create. Only used if type is “resources”. Either “COMPUTER” or “DOOR”

return:
{success: "Group has been successfully created!", group_id: 2}, 200
{"error": "error message"}, !200 on failure
The response will contain the ID of the group you created.
To modify the users of a group, do the following:
Make a PUT request to /groups with the following eters:
type:

(Required) String users or resources

group_id:

(Required) Int representing the group id of the group being modified

add_ids:

(Optional) list of ids that will be added to the group

del_ids:

(Optional) list of ids that will be deleted from the group

return:
{success: "Group has been successfully updated!"}, 200
{"error": "error message"}, !200 on failure

Create PIN/SmartCard for users¶

To assign a PIN or SmartCard to a user, you will need to make an API call.
To make the API call, do the following:
Make a PUT request to the /modifysmartcards endpoint with the following parameters:
api_key required - The API key you generated in step 1.

email_id required - The ID of the user you wish to assign the smartcard to.

smartcards required - A Serialized JSON array of smartcards you wish to assign to the user.
[ {"number": "<integer string>", (optional) "label": "<label string>" }, ... ]
allow_duplicates optional - A boolean value that determines whether to allow duplicate smartcards.

Create Guest Links¶

You can customize Guest Links to fine-tune user access to resources.
To make the API call, do the following:
Make a POST request to the /magiclinkadmin endpoint with the following eters:

email_list:

(Required) An array of emails for users that you want to provide the magic link to

resource_id_list:

(Required) The resource ID that you want to provide access to. Note: These must be

doors! :end_time: (Required) A date and time to expire this link in UTC (YYYY-MM-DD hh:mm:ss) [Default: never] :name: (Required) This is the name of this policy that will make it easier to manage later :send_email: (Optional) If this is set to False, we will not automatically send this link to

them in an email
start_time:

(Optional) A date and time to activate this link in UTC (YYYY-MM-DD hh:mm:ss) [Default: now]

config_id:

(Optional) The configuration ID that you want to use for this link.

smartcards:

(Optional) An array of dictionary of smartcards containing the ‘label’ and ‘number’ field mapped 1-1 for the emails.e.g [{“label”: “<label>”, “number”: “<number>”}]

allow_duplicates:

(Optional) If this is set to True, we will allow smartcard to be added even if someone else in the org, owns the smartcard number.

time_mapping:
(Optional) An array of days of the week (7 elements) and the range of times that this link should be active. [Default is 24/7 access]
With the week starting on Sunday, each element contains a list of active ranges. For example, 24/7 access looks like this:
[[[0,24]],[[0,24]], ...]
9 am - 5 pm work days only:
[[],[[9,17]],[[9,17]], ... ,[]]
And, 9-noon and 1pm-5pm would be:
[[],[[9,12],[13,17]], [[9,12],[13,17]], ... ,[]]
return:

Returns a magic token that can be used to unlock the resource and dictionary (email_ids) that maps
emails to email_ids
Example: https://magic.allthenticate.com/?magic_token=MAGIC_TOKEN&email=EMAIL_ADDRESS
{"success": "Successfully created a new temporary policy and magic link.",
"magic_token": "WufGylsf1w0ZFZfYAw8_ziK3KxDOYQ16IPLwgSpFg9WjJzQZF-u8XLKU7fQsTB8gCnuUlm1OHA0wjxBzGFFkOg",
"email_ids": {"email@address.com": <email_id>},
"config_id": ID of the configuration that was used,
"magic_link_id": ID of the newly created magic link,
}

Locking and Unlocking Doors¶

To lock or unlock a door, you will need to make an API call.
To make the API call, do the following:
Make a POST request to the /setlockstatus endpoint with the following parameters:
uuid:

(Required) String UUID of the resource that will have its lock state changed.

lock_state:

(Required) Boolean value determining if resource will be locked or unlocked. True = locked.

unlock_time:

(Optional) Int how long you want the door to stay unlock for, in seconds

return:
{"error"/"success": message}, http_code
The response will contain a message indicating the status of the door.