Skip to main content

LoginID Service API (0.1.5)

Introduction

Welcome to the LoginID API docs. This documentation will help understand the API calls being made behind our SDKs.

These APIs can be used to manage authentication, users, and user credentials.

Authentication

There is one main form of authentication for the API:
• API Service Token

Register

Endpoints to perform registration.

Initiate user registration (FIDO2)

Service token scope: auth.register

header Parameters
Request-ID
string <uuid>
Request Body schema: application/json
client_id
string
username
string
object

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "username": "string",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "attestation_payload": {
    },
  • "register_session": "b34877e9-54ac-4c43-8ea8-5b9bd8732980"
}

Finalize user registration (FIDO2)

header Parameters
Request-ID
string <uuid>
Request Body schema: application/json
client_id
string
username
string
object
object

Responses

Request samples

Content type
application/json
{
  • "client_id": "MjE4MDA4NTgtMmI0NS0xMWViLWFkYzEtMDI0MmFjMTIwMDAyLg==",
  • "username": "john.doe",
  • "attestation_payload": {
    },
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "client": {
    },
  • "credential": {
    },
  • "user": {
    },
  • "jwt": "string",
  • "is_authenticated": true
}

User registration (password)

Service token scope: auth.register

header Parameters
Request-ID
string <uuid>
Request Body schema: application/json
client_id
string
username
string
password
string
password_confirmation
string
object

Responses

Request samples

Content type
application/json
{
  • "client_id": "MjE4MDA4NTgtMmI0NS0xMWViLWFkYzEtMDI0MmFjMTIwMDAyLg==",
  • "username": "john.doe",
  • "password": "string",
  • "password_confirmation": "string",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "client": {
    },
  • "credential": {
    },
  • "user": {
    },
  • "jwt": "string",
  • "is_authenticated": true
}

Initiates user registration process Deprecated

header Parameters
Origin
required
string
Request-ID
string <uuid>
Request Body schema: application/json
clientId
string
udata
string
sessionId
string

Responses

Request samples

Content type
application/json
{
  • "clientId": "string",
  • "udata": "string",
  • "sessionId": "string"
}

Response samples

Content type
application/json
{
  • "strategies": [
    ]
}

Finalize user registration process Deprecated

header Parameters
Origin
required
string
Request-ID
string <uuid>
Request Body schema: application/json
client_id
string
username
string
strategy
string
object

Responses

Request samples

Content type
application/json
{
  • "client_id": "MjE4MDA4NTgtMmI0NS0xMWViLWFkYzEtMDI0MmFjMTIwMDAyLg==",
  • "username": "john.doe",
  • "strategy": "fido2",
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "jwt": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZ....",
  • "uid": "b7bd9990-2c43-4dce-9286-93cccf81bc62",
  • "username": "john.doe",
  • "organization": "07523c4752bc7168"
}

Authenticate

Endpoints to perform authentication

Initiate user login (AuthID)

Service token scope: auth.login

header Parameters
Request-ID
string <uuid>
Request Body schema: application/json
client_id
string
username
string
object

Responses

Request samples

Content type
application/json
{
  • "client_id": "MjE4MDA4NTgtMmI0NS0xMWViLWFkYzEtMDI0MmFjMTIwMDAyLg==",
  • "username": "john.doe",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "credential_uuid": "string",
  • "iframe_url": "string"
}

Finalize user login (AuthID)

header Parameters
Request-ID
string <uuid>
Request Body schema: application/json
client_id
string
username
string
credential_uuid
string

Responses

Request samples

Content type
application/json
{
  • "client_id": "MjE4MDA4NTgtMmI0NS0xMWViLWFkYzEtMDI0MmFjMTIwMDAyLg==",
  • "username": "john.doe",
  • "credential_uuid": "string"
}

Response samples

Content type
application/json
{
  • "client": {
    },
  • "credential": {
    },
  • "user": {
    },
  • "jwt": "string",
  • "is_authenticated": true
}

Initiate user login (FIDO2)

Service token scope: auth.login

header Parameters
Request-ID
string <uuid>
Request Body schema: application/json
client_id
string
username
string
object

Responses

Request samples

Content type
application/json
{
  • "client_id": "MjE4MDA4NTgtMmI0NS0xMWViLWFkYzEtMDI0MmFjMTIwMDAyLg==",
  • "username": "john.doe",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "assertion_payload": {
    }
}

Finalize user login (FIDO2)

header Parameters
Request-ID
string <uuid>
Request Body schema: application/json
client_id
string
username
string
object

Responses

Request samples

Content type
application/json
{
  • "client_id": "MjE4MDA4NTgtMmI0NS0xMWViLWFkYzEtMDI0MmFjMTIwMDAyLg==",
  • "username": "john.doe",
  • "assertion_payload": {
    }
}

Response samples

Content type
application/json
{
  • "client": {
    },
  • "credential": {
    },
  • "user": {
    },
  • "jwt": "string",
  • "is_authenticated": true
}

User login (password)

Service token scope: auth.login

header Parameters
Request-ID
string <uuid>
Request Body schema: application/json
client_id
string
username
string
password
string
object

Responses

Request samples

Content type
application/json
{
  • "client_id": "MjE4MDA4NTgtMmI0NS0xMWViLWFkYzEtMDI0MmFjMTIwMDAyLg==",
  • "username": "john.doe",
  • "password": "string",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "client": {
    },
  • "credential": {
    },
  • "user": {
    },
  • "jwt": "string",
  • "is_authenticated": true
}

User login (authentication code)

Service token scope: auth.temporary

header Parameters
Request-ID
string <uuid>
Request Body schema: application/json
client_id
string
username
string
object

Responses

Request samples

Content type
application/json
{
  • "client_id": "MjE4MDA4NTgtMmI0NS0xMWViLWFkYzEtMDI0MmFjMTIwMDAyLg==",
  • "username": "john.doe",
  • "authentication_code": {
    }
}

Response samples

Content type
application/json
{
  • "client": {
    },
  • "credential": {
    },
  • "user": {
    },
  • "jwt": "string",
  • "is_authenticated": true
}

Initiate user login process Deprecated

header Parameters
Origin
required
string
Request-ID
string <uuid>
Request Body schema: application/json
clientId
string
username
string
object

Responses

Request samples

Content type
application/json
{
  • "clientId": "MjE4MDA4NTgtMmI0NS0xMWViLWFkYzEtMDI0MmFjMTIwMDAyLg==",
  • "username": "john.doe",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "strategies": [
    ]
}

Finalize user login process Deprecated

header Parameters
Origin
required
string
Request-ID
string <uuid>
Request Body schema: application/json
client_id
string
username
string
strategy
string
object

Responses

Request samples

Content type
application/json
{
  • "client_id": "MjE4MDA4NTgtMmI0NS0xMWViLWFkYzEtMDI0MmFjMTIwMDAyLg==",
  • "username": "john.doe",
  • "strategy": "fido2",
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "jwt": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZ....",
  • "uid": "b7bd9990-2c43-4dce-9286-93cccf81bc62",
  • "username": "john.doe",
  • "organization": "07523c4752bc7168"
}

Transactions

Endpoints to create and confirm transactions

Create transaction

Service token scope: tx.create

Request Body schema: application/json
client_id
string
tx_type
string
tx_payload
string
nonce
string
username
string

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "tx_type": "string",
  • "tx_payload": "string",
  • "nonce": "string",
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "tx_id": "string",
  • "url": "string"
}

Initialize confirmation of transaction

Service token scope: tx.create if tx_payload given instead of tx_id

Request Body schema: application/json
client_id
string
username
string
nonce
string
tx_type
string
tx_id
string

ID of already-created transaction; not applicable if tx_payload given

tx_payload
string

Payload of transaction to create; not applicable if tx_id given

Responses

Request samples

Content type
application/json
{
  • "client_id": "MjE4MDA4NTgtMmI0NS0xMWViLWFkYzEtMDI0MmFjMTIwMDAyLg==",
  • "username": "john.doe",
  • "nonce": "PtREk2Lza7KvjHda",
  • "tx_type": "text",
  • "tx_id": "transaction id",
  • "tx_payload": "transaction text to be signed"
}

Response samples

Content type
application/json
{
  • "tx_id": "5de548f0-caa2-4a5f-93f3-066ae6fc8feb",
  • "assertion_options": {
    }
}

Create and initialize transaction

Service token scope: tx.create

Request Body schema: application/json
client_id
string
username
string
nonce
string
tx_type
string
tx_payload
string

Responses

Request samples

Content type
application/json
{
  • "client_id": "MjE4MDA4NTgtMmI0NS0xMWViLWFkYzEtMDI0MmFjMTIwMDAyLg==",
  • "username": "john.doe",
  • "nonce": "PtREk2Lza7KvjHda",
  • "tx_type": "text",
  • "tx_payload": "transaction text to be signed"
}

Response samples

Content type
application/json
{
  • "tx_id": "5de548f0-caa2-4a5f-93f3-066ae6fc8feb",
  • "assertion_options": {
    }
}

Complete transaction with signature

Request Body schema: application/json
tx_id
string
client_id
string
username
string
challenge
string
key_handle
string
client_data
string
auth_data
string
sign_data
string

Responses

Request samples

Content type
application/json
{
  • "tx_id": "5de548f0-caa2-4a5f-93f3-066ae6fc8feb",
  • "client_id": "MjE4MDA4NTgtMmI0NS0xMWViLWFkYzEtMDI0MmFjMTIwMDAyLg==",
  • "username": "john.doe",
  • "challenge": "pO9V4DruYKrXClSwUn9pRIapBfFcl_l0khQd7YwqQRE",
  • "key_handle": "5dEDbWqk0BAc1lKwFI057rkTHPd7zHBvlDb5pd_HlTw",
  • "client_data": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoicE85VjREcnVZS3JYQ2x",
  • "auth_data": "b7bd9990-2c43-4dce-9286-93cccf81bc62",
  • "sign_data": "x2QYJ3SZVncERjV58EciojIldmblxGiIlRXYlJ3Yu4Ga0VXYiV2diojIlBXe0Jye"
}

Response samples

Content type
application/json
{
  • "jwt": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZ...."
}

Codes

Endpoints to manage codes

Generate authentication code

Service token scope: codes.generate

Authorizations:
serviceToken
path Parameters
code_type
required
string
Enum: "short" "long" "phrase"

Type of code to be generated

header Parameters
Request-ID
string <uuid>
Request Body schema: application/json
client_id
string
user_id
string
purpose
string
Enum: "add_credential" "temporary_authentication"
authorize
boolean

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "user_id": "string",
  • "purpose": "add_credential",
  • "authorize": true
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "is_authorized": true
}

Authorize authentication code

Service token scope: codes.authorize

Authorizations:
serviceToken
path Parameters
code_type
required
string
Enum: "short" "long" "phrase"

Type of code to be authorized

header Parameters
Request-ID
string <uuid>
Request Body schema: application/json
client_id
string
user_id
string
purpose
string
Enum: "add_credential" "temporary_authentication"
code
string

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "user_id": "string",
  • "purpose": "add_credential",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "expires_at": "2019-08-24T14:15:22Z",
  • "is_authorized": true
}

Invalidate all authentication codes of given type and purpose for given user

Service token scope: codes.invalidate

Authorizations:
serviceToken
path Parameters
code_type
required
string
Enum: "short" "long" "phrase"

Type of code to be denied

header Parameters
Request-ID
string <uuid>
Request Body schema: application/json
client_id
string
user_id
string
purpose
string
Enum: "add_credential" "temporary_authentication"

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "user_id": "string",
  • "purpose": "add_credential"
}

Response samples

Content type
application/json
{
  • "deleted_at": "2019-08-24T14:15:22Z"
}

Credentials

Endpoints to manage user credentials

Retrieve credentials for user

Service token scope: credentials.list

Authorizations:
serviceToken
query Parameters
user_id
required
string <uuid>

User ID to retrieve credentials for

header Parameters
X-Client-ID
required
string

Management API client ID which is created on LoginID admin dashboard.

Request-ID
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "user_id": "string",
  • "credentials": [
    ]
}

Rename user's credential

Service token scope: credentials.rename

Authorizations:
serviceToken
header Parameters
Request-ID
string <uuid>
Request Body schema: application/json
client_id
string
user_id
string
object

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "user_id": "string",
  • "credential": {
    }
}

Response samples

Content type
application/json
{
  • "user_id": "string",
  • "credential": {
    }
}

Revoke user's credential

Service token scope: credentials.revoke

Authorizations:
serviceToken
header Parameters
Request-ID
string <uuid>
Request Body schema: application/json
client_id
string
user_id
string
object

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "user_id": "string",
  • "credential": {
    }
}

Response samples

Content type
application/json
{
  • "user_id": "string",
  • "credential": {
    }
}

Generate a recovery code

Service token scope: credentials.recovery_code

Authorizations:
serviceToken
header Parameters
Request-ID
string <uuid>
Request Body schema: application/json
client_id
string
user_id
string

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "user_id": "string"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Initiate adding a new FIDO2 credential

Service token scope: credentials.add

Authorizations:
serviceToken
header Parameters
Request-ID
string <uuid>
Request Body schema: application/json
client_id
string
username
string
object
object

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "username": "string",
  • "authentication_code": {
    },
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "attestation_payload": {
    }
}

Begin adding FIDO2 authenticator as new credential (initiated by client backend)

Service token scope: credentials.force_add

header Parameters
Request-ID
string <uuid>
Request Body schema: application/json
client_id
required
string
user_id
required
string
object

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "user_id": "string",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "attestation_payload": {
    }
}

Finalize adding a new FIDO2 credential

header Parameters
Request-ID
string <uuid>
Request Body schema: application/json
client_id
string
username
string
object
object

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "username": "string",
  • "attestation_payload": {
    },
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "credential_uuid": "b7bd9990-2c43-4dce-9286-93cccf81bc62",
  • "username": "john.doe",
  • "namespace_id": "07523c4752bc7168",
  • "jwt": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZ...."
}

Initiate adding a new AuthID credential

Service token scope: credentials.force_add

Authorizations:
serviceToken
header Parameters
Request-ID
string <uuid>
Request Body schema: application/json
client_id
required
string
user_id
required
string
object

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "user_id": "string",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "credential_uuid": "string",
  • "iframe_url": "string"
}

Retrieve AuthID data for evaluation

header Parameters
Request-ID
string <uuid>
Request Body schema: application/json
client_id
required
string
username
string
user_id
string
credential_uuid
string

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "username": "string",
  • "user_id": "string",
  • "credential_uuid": "string"
}

Response samples

Content type
application/json
{
  • "result_url": "https://...",
  • "token_type": "Bearer",
  • "auth_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZ...."
}

Finalize adding a new AuthID credential

header Parameters
Request-ID
string <uuid>
Request Body schema: application/json
client_id
required
string
username
string
user_id
string
credential_uuid
string
activate_credential
boolean

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "username": "string",
  • "user_id": "string",
  • "credential_uuid": "string",
  • "activate_credential": true
}

Response samples

Content type
application/json
{
  • "credential_uuid": "b7bd9990-2c43-4dce-9286-93cccf81bc62",
  • "username": "john.doe",
  • "namespace_id": "07523c4752bc7168",
  • "jwt": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZ...."
}

Management

Endpoints to manage users

Create a new user without credentials

Service token scope: users.create

Authorizations:
serviceToken
header Parameters
Request-ID
string <uuid>
X-Client-ID
required
string
Request Body schema: application/json
username
string

Responses

Request samples

Content type
application/json
{
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "client_id": "string",
  • "username": "string",
  • "status": "string",
  • "type": "string",
  • "namespace_id": "string",
  • "created_at": "2019-08-24",
  • "updated_at": "2019-08-24",
  • "contacts": [
    ]
}

Retrieve a user profile by username

Service token scope: users.retrieve

Authorizations:
serviceToken
header Parameters
X-Client-ID
required
string

Management API client ID which is created on LoginID admin dashboard.

Request Body schema: application/json
username
string

Responses

Request samples

Content type
application/json
{
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "client_id": "string",
  • "username": "string",
  • "status": "string",
  • "type": "string",
  • "namespace_id": "string",
  • "created_at": "2019-08-24",
  • "updated_at": "2019-08-24",
  • "contacts": [
    ]
}

Delete a user record by username

Service token scope: users.delete

Authorizations:
serviceToken
header Parameters
X-Client-ID
required
string

Management API client ID which is created on LoginID admin dashboard.

Request Body schema: application/json
username
string

Responses

Request samples

Content type
application/json
{
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "code": "user_not_deleted",
  • "message": "Failed to delete the user"
}

Delete a user record by user id

Service token scope: users.delete

Authorizations:
serviceToken
path Parameters
user_id
required
string

Unique ID of the user to be deleted.

header Parameters
X-Client-ID
required
string

Management API client ID which is created on LoginID admin dashboard.

Responses

Response samples

Content type
application/json
{
  • "code": "user_not_deleted",
  • "message": "Failed to delete the user"
}

Activate a user account

Service token scope: users.activate

Authorizations:
serviceToken
path Parameters
user_id
required
string

Unique ID of the user to be deleted.

header Parameters
X-Client-ID
required
string

Management API client ID which is created on LoginID admin dashboard.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "client_id": "string",
  • "username": "string",
  • "status": "string",
  • "type": "string",
  • "namspace_id": "string",
  • "created_at": "2019-08-24"
}

Deactivate a user account

Service token scope: users.deactivate

Authorizations:
serviceToken
path Parameters
user_id
required
string

Unique ID of the user to be deleted.

header Parameters
X-Client-ID
required
string

Management API client ID which is created on LoginID admin dashboard.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "client_id": "string",
  • "username": "string",
  • "status": "string",
  • "type": "string",
  • "namspace_id": "string",
  • "created_at": "2019-08-24"
}

Send email verificaiton request to a user

Service token scope: users.email_verification_dispatch

Authorizations:
serviceToken
path Parameters
user_id
required
string

Unique ID of the user to be deleted.

header Parameters
X-Client-ID
required
string

Management API client ID which is created on LoginID admin dashboard.

Responses

Response samples

Content type
application/json
{
  • "code": "email_verification_not_sent",
  • "message": "Failed to dispatch email verification."
}