How to relationship or link a sender with roles by API Rest

Hi gecarrizo,

Thanks for your post! Assuming your account has Roles & Permissions feature turned on, in order to further assign role(s) to a sender, use this API:

POST /api/account/senders/{senderId}/account/{account_or_subaccount_id}/roles

With payload:
 

[

  {

    "id": "owner"

  },

  {

    "id": "member"

  },

  {

    "id": "manager"

  },

  {

    "id": "dc996466-8a0a-40d2-a9fb-461de2c2fab7"

  }

]

Note:
(1) "owner", "manager" and "member" are preserved role IDs, IDs in UUID format are customized roles.

(2) you need to at least provide role "id" for each node.

Duo

HI Duo.

The "id" that is passed in the payload to which it corresponds?

 I understand that it must be the user ID to achieve the user / role relationship.

Regards

Gabriel

Hi Gabriel,

It references to the Role ID (for Roles & Permissions feature). You can get all the account roles using this API:
GET /api/account/roles
 

Duo

Duo, thanks for your answer.

How do I reference in the payload the user ID that I want to refer to and that I want to assign a role to? 

Attached images.(NegativeResultByAPI.png and ExpectedResultByAPI.png)

Regards

Gabriel

I see, use this API to search the sender by his/her email:
GET /api/account/senders?search={sender_email}

Because the API may return multiples senders whose emails are very alike, don't forget to loop through the results and filter by the exact email.

The sender ID will also be returned when you invited the sender with API:

POST /api/account/senders

Duo

Duo, I have the user ID. This is returned to me in the response payload when creating the user. Now, I need to bind that user with a role by API. What endpoint should I use to make this binding and how the request payload should be made up?

Regards

Gabriel

Hi Gabriel

In that case, you need this API:

POST /api/account/senders/{senderId}/account/{account_or_subaccount_id}/roles

With payload:
 

[

  {

    "id": "owner"

  },

  {

    "id": "member"

  },

  {

    "id": "manager"

  },

  {

    "id": "dc996466-8a0a-40d2-a9fb-461de2c2fab7"

  }

]

The sender ID has been implied in the API URL and the Account Role IDs can be listed by this API:

GET ​/api​/account​/roles

Did I miss something here?

Duo

I understand Duo.

Could you tell me how to get the parameter {account_or_subaccount_id}?

Regards

Gabriel

Hi Gabriel,

Sure! If you haven't turned on subaccount feature, your main account ID is fixed and can be found in the GET /api/account/senders call.

If you are referring to a subaccount, use this call to list all the subaccounts:

GET /api/account/subaccounts

Duo

Hi Duo
Returning to the topic, I have executed in Postman the follow:

In URL endpoint I replace sender Id with {senderId}

POST
https://sandbox.esignlive.com/api/account/senders/{senderId}/account/6YOBAtp3Y8oB/roles

payload

{
    "id": "member"
 }

I get as result "400Bad Request":

{
    "technical": "Failed to deserialize json string to target type java.util.List<com.silanis.esl.permission.api.model.AccountRole>",
    "messageKey": "error.validation.invalidJson",
    "message": "Invalid JSON.",
    "code": 400,
    "name": "Validation Error"
}

Am I building the payload wrong?

Regards
Gabriel
 

Hi Gabriel,

Please add a pair of brackets around the payload and try again:

[

    {
        "id": "member"
    }

]

Duo

Duo, thanks for your quick reply. We almost made it.

TRY 1

I fixed the payload.

POST
https://sandbox.esignlive.com/api/account/senders/{senderId}/account/6YOBAtp3Y8oB/roles

[
   {
    "id": "member"
   }
]

I get as result "404Not Found":

{
    "technical": "Account with UID '6YOBAtp3Y8oB' was not found.",
    "messageKey": "error.notFound.accountNotFound",
    "message": "The specified account cannot be found.",
    "code": 404,
    "name": "Resource Not Found"
}

TRY 2

POST
I fixed Account Id, because I had taken the "Id" from the company (6YOBAtp3Y8oB)

https://sandbox.esignlive.com/api/account/senders/{senderId}/account/QKEgqMujKTYK/roles

[
   {
    "id": "member"
   }
]

I get as result "500Internal Server Error":

{
    "messageKey": "error.internal.default",
    "message": "Unexpected error. We apologize for any inconvenience this may have caused you, please try again. If the problem persists, please contact our support team.",
    "code": 500,
    "name": "Unhandled Server Error"
}

I got an error but it worked. The user has an assigned role.

Could it be a OneSpan problem? 

Regards

Gabriel Carrizo

Hi Gabriel,

Thanks for letting me know! I believe your account only has Roles & Permissions feature turned on, without the Subaccount feature, correct? In which case, I think we found something interesting that instead of using this API: 

POST /api/account/senders/{senderId}/account/{accountId}/roles

You could simplify the API and don't specifying the account ID:

POST /api/account/senders/{senderId}/roles

Please try and let me know if this works for you.

At the same time, thanks for your suggestion and documentation team and I are working actively on creating a feature guide on "Account Role", I will make sure this finding is also highlighted in the guide!

Duo