Skip to main content

SCIM OTP devices examples

Operations

This page shows the operations that can be performed for the OTP devices object.

List all

Request
GET http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice
Response 200 OK
{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 25,
    "startIndex": 1,
    "Resources": [
        {
            "lastUsed": "2021-10-14 06:57:00",
            "created": "2021-10-14 06:44:43",
            "meta": {
                "location": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4022880",
                "links": {
                    "requestChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4022880/requestChallenge",
                    "responseChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4022880/responseChallenge"
                },
                "resourceType": "OtpDevice"
            },
            "schemas": [
                "urn:soffid:com.soffid.iam.addons.otp.common.OtpDevice"
            ],
            "name": "TOTP00000001",
            "id": 4022880,
            "type": "TOTP",
            "user": "franck",
            "fails": 0,
            "status": "D"
        },
        {
            "created": "2021-10-14 08:37:38",
            "meta": {
                "location": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4024384",
                "links": {
                    "requestChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4024384/requestChallenge",
                    "responseChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4024384/responseChallenge"
                },
                "resourceType": "OtpDevice"
            },
            "schemas": [
                "urn:soffid:com.soffid.iam.addons.otp.common.OtpDevice"
            ],
            "name": "Email message to pg*****@so****.co*",
            "id": 4024384,
            "type": "EMAIL",
            "user": "patricia",
            "fails": 0,
            "email": "patricia@soffid.com",
            "status": "D"
        },
        {
            "created": "2021-10-14 11:17:52",
            "meta": {
                "location": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4024416",
                "links": {
                    "requestChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4024416/requestChallenge",
                    "responseChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4024416/responseChallenge"
                },
                "resourceType": "OtpDevice"
            },
            "schemas": [
                "urn:soffid:com.soffid.iam.addons.otp.common.OtpDevice"
            ],
            "phone": "666555444",
            "name": "SMS message to 66*****44",
            "id": 4024416,
            "type": "SMS",
            "user": "agatha",
            "fails": 0,
            "status": "V"
        },
      .............
      .............
    ]
}

List by filter

List all the OTP devices with a filter expression.

It is allowed to use pagination and sort the information, for more information visit the Sorting and Pagination information.

Request
GET http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice?filter=type eq "TOTP"
Response 200 OK
{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 7,
    "startIndex": 1,
    "Resources": [
        {
            "lastUsed": "2021-10-14 06:57:00",
            "created": "2021-10-14 06:44:43",
            "meta": {
                "location": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4022880",
                "links": {
                    "requestChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4022880/requestChallenge",
                    "responseChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/4022880/responseChallenge"
                },
                "resourceType": "OtpDevice"
            },
            "schemas": [
                "urn:soffid:com.soffid.iam.addons.otp.common.OtpDevice"
            ],
            "name": "TOTP00000001",
            "id": 4022880,
            "type": "TOTP",
            "user": "franck",
            "fails": 0,
            "status": "D"
        },
      .............
      .............
    ]
}

Query by id

Query a OTP device by its id (primary key). 

Request
GET http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice/5007882
Response 200 OK
{
    "created": "2022-02-22 07:46:51",
    "meta": {
        "location": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/5007882",
        "links": {
            "requestChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/5007882/requestChallenge",
            "responseChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/5007882/responseChallenge"
        },
        "resourceType": "OtpDevice"
    },
    "schemas": [
        "urn:soffid:com.soffid.iam.addons.otp.common.OtpDevice"
    ],
    "name": "TOTP00000035",
    "id": 5007882,
    "type": "TOTP",
    "user": "admin",
    "fails": 0,
    "status": "C"
}

Create

Allows you to create a new OTP device. It is important the type of the OTP you want to create, and depending on this, it will be mandatory to add new attributes to the request.

  • SMS: add to the JSON the phone attribute
  • EMAIL: add to the JSON the email attribute
  • PIN: add to the JSON the pin attribute
Request
http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice

JSON

{
    "meta": {
        "location": "http://<your-domain>/webservice/scim2/v1/OtpDevice",
        "resourceType": "OtpDevice"
    },
    "schemas": [
        "urn:soffid:com.soffid.iam.addons.otp.common.OtpDevice"
    ],
    "type": "TOTP",
    "user": "admin"
}
Response 200 OK
{
    "image": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADIAQAAAACFI5MzAAAC3klEQVR4Xu2XP66jMBDGB7lwFy5gydeg40rkAoRcgFzJna+B5AtA58Ji9hueQvJWu8UbS6stMoqiwA9lrPn7Qfw3o99vnPYhHyL2L0mghhOz2Xue+tJGIltBIm9haQPdgufsButxp4LQlc1M+C5tSLt1TSWJyy26Jvipd2NfTTJPHU/kmlxariS8RX6w2fhwwt+i82OC/ER3fX2+Ze7HBJbp0iGieCQh54dpSaCBaOz8SmbukfY0C1STJAHIZkdQe947d6khkYau3KKZrNktzs77MwYawoTCuTFqEDytHY1PPxqSEQPPwY3WoOeu0WzPbGtIoNH6tTdzt1BX2ky3w7mSZAnkA95sQge3eRmfMdAQhh8pwLFL94ACR/9VkOzvbB5oX0LnuaEz9xoS/YORcNROGY7jn/nREE5bwCRwFwtveOQtBgoSJc9rnzggOWm27nUCBcnws1wI3OPgeOpVVQqCkdynqU+rLWQx+fwxEtTEEZXBLoO4KjcpzAqScZWQbczRNphZOq+CBHcNkuQmSs+hm4enHw1hXBWM9o39PS4XW161oyBhIZt2MishP/imy3kCDUEAyo3LpZe2m/BUDYlmtdjbUoDYtIQNyRUkLPj7jdNE5g4hIKVUQWK5BszRQh3PWBf0pncUJCAhRjJDGPZokbdtpiCMooYHs8rZ4WehKuIhnZqM0YIKSo+czsmnIRFKpxyyArfd8FY7GoKRzISg7gSInqsj2UwdYVZh+c+9jATMZj2J0rUi7ix0YsFsFt9qIrtR5PA9o10wYPx0nlpDjJRhD4Xi0MoP6NnTj4KEQ4WJFvNbXlDWZ+1oCCwujWhYg7S3sVQR0bDUYj3GI+3xpa81BPoah+3T/UvDygqqIShDNxIq2q8dftD7W4GGRLyBYT0ujdRRedOwOgKRgvMiS446z2JqwjKfMJUJextCm87dqCHIj+xGj0WxMbT/8v7G8mPyZ/uQDxH7n8kvJ2XgRr9Rxi0AAAAASUVORK5CYII=",
    "created": "2022-02-22 07:46:51",
    "meta": {
        "location": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/5007882",
        "resourceType": "OtpDevice"
    },
    "schemas": [
        "urn:soffid:com.soffid.iam.addons.otp.common.OtpDevice"
    ],
    "name": "TOTP00000035",
    "id": 5007882,
    "type": "TOTP",
    "user": "admin",
    "fails": 0,
    "status": "C"
}
Example JSON SMS
{
    "type": "SMS",
    "user": "dilbert",
    "phone": "6665552222"
}
Example JSON EMAIL
{
    "type": "EMAIL",
    "user": "dilbert",
    "email": "dilbert@soffid.com"
}
Example JSON PIN
{
    "type": "PIN",
    "user": "dilbert",
    "email": "123456789"
}

Update partial

Only attributes with changes will be updated, the other will mantain the same value. This example shows how  to enable an OTP device.

Request
PATCH http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice/5007882

JSON

{
    "Operations": 
    [
        {
            "op": "replace",
            "path": "status",
            "value": "V"
        }
    ]
}
Response 200 OK
{
    "created": "2022-02-22 07:46:51",
    "meta": {
        "location": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/5007882",
        "links": {
            "requestChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/5007882/requestChallenge",
            "responseChallenge": "http://soffid.pat.lab:8080/soffid/webservice/scim2/v1/OtpDevice/5007882/responseChallenge"
        },
        "resourceType": "OtpDevice"
    },
    "schemas": [
        "urn:soffid:com.soffid.iam.addons.otp.common.OtpDevice"
    ],
    "name": "TOTP00000035",
    "id": 5007882,
    "type": "TOTP",
    "user": "admin",
    "fails": 0,
    "status": "V"
}

Request Challenge

This operation allows Soffid to obtain the PIN code for a specific OTP device. We can use this method to send an email or SMS, depending on the type of OTP device.

Request
GET http://<your-domain>//soffid/webservice/scim2/v1/OtpDevice/<OTP_ID>/requestChallenge
Response 200 OK
{
    "cell": "PIN",
    "cardNumber": "SMS message to 66*****22"
}

    Response Challenge

    This operation allows you to validate a PIN code for a specific OTP device.

      Request
      POST http://<your-domain>//soffid/webservice/scim2/v1/OtpDevice/<OTP_ID>/responseChallenge

      JSON

      {
    "pin": "12345678"
}
      Response 200 OK
      {
    "success": false,
    "locked": false
}

      Delete

      In this case, delete operation will cancel the TaskInstace, but does not be deleted form database.

      Please note after this delete, the account has to be created again to use it in the next examples.

      Request
      DELETE - http://<your-domain>/soffid/webservice/scim2/v1/OtpDevice/5007967
      Response 204 No Content
      204 No Content

      Error response

      For more information about error response visit https://bookstack.soffid.com/link/116#bkmrk-error-response


      Back to top