Creating Permissions through Admin API

~ minute read
This is available in UserVoice Discovery Premium.

Not included in your plan? Want to learn more about the benefits? Leave us a message! If you're viewing this on our Help Center, click the Support bubble in the lower-right of this page.

 

Configure the Client

To connect to the UserVoice API, start by creating a trusted API client. Do this in your UserVoice Admin Console by navigating to Settings → Integrations → UserVoice API keys. Click the button that says “Add API Key…” and enter a name for for the client. Use a name that will help you keep track of where the token will be used (e.g Zapier Integration, or Nightly Export to BI). Leave the “APPLICATION URL” and “CALLBACK URL” text fields blank, and make sure the “Trusted” checkbox is checked. Then click the button labelled “Add API key” to create the client.

Getting your key and secret

Best Practices: You can create multiple clients for specific purposes through this user interface. It’s a good idea to use a separate key for each kind of interaction that you want to build with the API. By doing so, you safely revoke keys as your needs evolve.

Warning: Never store trusted client credentials in an insecure environment (for example: in your client-side JavaScript or a public source code repository). Trusted clients have full access to perform the same actions that admins do, including deleting content.

Remember: The UserVoice API requires all calls to be made over HTTPs.

Getting the Token

To make an API call, you’ll next need to generate a token. There are two ways to do this, either through the user interface or by using the API itself.

To generate and display the token in the user interface, find your client by name in the list and click the “Create” link.

Creating your API key

A dialog will appear with your token.

Getting your API token

You can alternatively request a token for your UserVoice account owner with the API key and secret. Here’s how it would be done with curl:

1
2

$ curl https://SUBDOMAIN.uservoice.com/api/v2/oauth/token \
       --data "grant_type=client_credentials;client_id=KEY;client_secret=SECRET"

Example response:

1

{"access_token": "096e8ae9c6a3c039"}

For clients where the API secret and not be safely secured, please see OAuth Authorization Code Flow with PKCE.

 

Rate Limiting

API requests have per-minute rate limiting. Each request counts toward your limit. Not all requests are created equal: if a request takes longer than 1 second to compute then another “request” is counted for every whole second after the first. This helps us account for expensive endpoints (like complex searches) that use more resources.

Once you have exceeded your limit for the current minute, the UserVoice Idea Collection API will return a 429 HTTP error response for subsequent requests.

Every request returns the following HTTP headers:

  • X-Rate-Limit-Limit: The number of requests available every minute
  • X-Rate-Limit-Remaining: The number of requests remaining this period
  • X-Rate-Limit-Reset: The unix epoch in seconds when the limit resets

Once rate limited, every request returns the following HTTP header:

  • Retry-After: The unix epoch in seconds until the rate limit expires

The limit depends on your plan. See Terms of Service for details.

Take advantage of side-loading, per_page settings and bulk endpoints to consolidate your requests.

 

Permissions Endpoint

Create the endpoint: POST /api/v2/admin/permissions

To add permissions to users, this requires two parameters to pass: email and license_type 

The following strings are valid for license_type: "fullaccess_admin","admin","contributor", or"feedback_admin"

JSON example: 

1
2
3
4
5
6
7
 
POST /api/v2/admin/permissions
{
  "email": ["example@uservoice.com"],
  "license_type": "fullaccess_admin",
}

Updating Existing Permissions

First, you will need to find the permission record ID. To do this, use the List Permissions endpoint to find the record by the User ID.

Request: GET /api/v2/admin/permissions?user={id}

The permission record ID will appear in the response in the id attribute.

"permissions": [
  {
    "id": 123456,
    "license_type": "admin",
    "feedback": "manage",
    "features": "manage",
    "settings": "manage_account",
     "links": {
       "user": 123456789
     }
  }
]

You can now use this ID with the Update Permissions endpoint.

Request: PUT /api/v2/admin/permissions/123456 { "license_type": "contributor" }

Other Permission Parameters

 features
features (string) Nullable
Default: "none"
"none", "view", "manage"
 feedback
feedback (string) Nullable
Default: "contribute"
"none", "view","contribute", "manage"
 knowledgebase
knowledgebase (string) Nullable
Default:"none"
"none", "view", "manage"
 reply_to
reply_to (string) Nullable
 settings
settings (string) Nullable
Default: "none"
"none", "manage", "manage_account"

 

Related articles