Skip to main content

API_GetUserRole

 

Don't forget to check out our JSON RESTful APIs, they can help you utilize and extend Quickbase with ease.

Overview

Use API_GetUserRole to see what roles are assigned to a specific user in an application. Invoke this call on an application-level dbid.

Note that, if you do not have sharing permissions on the application, the API call returns your own roles only. To get your roles, you must either invoke the call with no user ID or supply your own user ID.

You  must have Basic Access with Sharing or Full Administration permissions to use this API call to get roles for users other than yourself.  Also, note that, if you want this call to return any roles assigned to a user because he or she is part of a group, you must use the inclgrps parameter (described below). If you do not specify this parameter, API_GetUserRole returns only those roles assigned to the individual user.

top

Request parameters

Parameter Value Required?

userid

The user ID of the user whose current role you want to retrieve. You can get the userid using API_GetUserInfo.

If you want to get your own roles, you can use your own userid or omit this parameter.

To get the roles of another user, you must supply the user's user id. You must also have Basic Access with Sharing or Full Administration permissions on the application.

no

ticket

A valid authentication ticket.

The authentication ticket is returned via the API_Authenticate call.

yes, one of:

  • ticket
  • username/password
  • user token

usertoken

The user token is an alternative means of authentication, used for API access. User tokens cannot be used to access the Quickbase UI.

yes, one of:

  • ticket
  • username/password
  • user token

inclgrps

Set this parameter to 1 if you want the call to return roles assigned to groups to which the user belongs.

The call will return additional information about the role's type--that is whether the role is a user role, a role assigned to a group role, or a role assigned to a domain group. (See Response Values, below.)

no

apptoken

A valid application token.

yes, if the application requires application tokens

udata

A string value that you want returned. It will not be handled by Quickbase but it will be returned in the response.

no

top

Response values

Element Name Value

action

The originating request, for example, API_GetUserRole.

errcode

Identifies the error code, if any. (See the Error Codes appendix for a list of possible error codes.)

0 indicates that no error was encountered.

errtext

Text that explains the error code.

"No error" indicates that no error was encountered.

user

The userid is returned as an attribute in this aggregate. The user aggregate also contains these parameters:

  • name -- the user name

  • roles -- an aggregate listing all roles to which the user belongs. The roles aggregate specifies these parameters:

    • role id -- the ID of the role

    • name -- the name of the role

    • access id -- the application access level for the role

    • member -- appears only if you've used inclgrps in the request. This parameter specifies the type of role. You can specify an attribute of “type.” Possible values are

        • user -- role is assigned to a user

        • group -- role is assigned to a group

        • domainGroup -- role is assigned to a domain group

 The following is an example of the user response:

<user id="112245.efy7">
   <name>John Doe</name>
   <roles>
     <role id="11">
     <name>Participant</name>
     <access id="3">Basic Access</access>
     <member type="user">John Doe</member>>
     </role>
   </roles>
</user>

udata

Optional. Contains any udata value supplied in the request.

top

Sample XML Request

POST https://target_domain/db/target_dbid HTTP/1.0
Content-Type: application/xml
Content-Length: 77
QUICKBASE-ACTION: API_GetUserRole

<qdbapi>
   <ticket>auth_ticket</ticket>
   <apptoken>app_token</apptoken>
   <inclgrps>1</inclgrps>
  <userid>112245.efy7</userid>
</qdbapi>

URL alternative

https://target_domain/db/target_dbid?a=API_GetUserRole&ticket=auth_ticket
&apptoken=app_token3&inclgrps=1&userid=112245.efy7

where target_domain is the domain against which you are invoking this call, for example, quickbase.com. Read about this notation.

top

Sample response

<?xml version="1.0" ?>
<qdbapi>
   <action>API_GetUserRole</action>
   <errcode>0</errcode>
   <errtext>No error</errtext>
   <user id="112245.efy7">
   <name>John Doe</name>
      <roles>
         <role id="11">
           <name>Participant</name>
           <access id="3">Basic Access</access>
           <member type="user">John Doe</member>
         </role>
         <role id="10">
           <name>Viewer</name>
           <access id="3">Basic Access</access>
           <member type="group">Group1</member>
         </role>
         <role id="12">
           <name>Administrator</name>
           <access id="1">Administrator</access>
           <member type="domainGroup">example.com</member>
         </role>
      </roles>
   </user>
</qdbapi>

Related articles

Top