Cloud

Jira Cloud platform / Reference / REST API v3

User properties

This resource represents user properties and provides for storing custom data against a user. Use it to get, create, and delete user properties as well as get a list of property keys for a user. This resourse is designed for integrations and apps to store per-user data and settings. This enables data used to customized the user experience to be kept in the Jira Cloud instance's database. User properties are a type of entity property.

This resource does not access the user properties created and maintained in Jira.

Operations

GET/rest/api/3/user/properties GET/rest/api/3/user/properties/{propertyKey}PUT/rest/api/3/user/properties/{propertyKey}DEL/rest/api/3/user/properties/{propertyKey}

GET

Get user property keys

Returns the keys of all properties for a user.

Note: This operation does not access the user properties created and maintained in Jira.

Permissions required:

Administer Jira global permission, to access the property keys on any user.
Access to Jira, to access the calling user's property keys.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-user

Granular:read:user.property:jira

Connect app scope required: READ

Request

Query parameters

accountId

string

userKey

string

username

string

Responses

Returned if the request is successful.

application/json

PropertyKeys

List of property keys.

GET/rest/api/3/user/properties

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asUser().requestJira(route`/rest/api/3/user/properties?accountId=5b10ac8d82e05b22cc7d4ef5`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

{
  "keys": [
    {
      "key": "issue.support",
      "self": "https://your-domain.atlassian.net/rest/api/3/issue/EX-2/properties/issue.support"
    }
  ]
}

GET

Get user property

Returns the value of a user's property. If no property key is provided Get user property keys is called.

Note: This operation does not access the user properties created and maintained in Jira.

Permissions required:

Administer Jira global permission, to get a property from any user.
Access to Jira, to get a property from the calling user's record.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-user

Granular:read:user.property:jira

Connect app scope required: READ

Request

Path parameters

propertyKey

string

Required

Query parameters

accountId

string

userKey

string

username

string

Responses

Returned if the request is successful.

application/json

EntityProperty

An entity property, for more information see Entity properties.

GET/rest/api/3/user/properties/{propertyKey}

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asUser().requestJira(route`/rest/api/3/user/properties/{propertyKey}?accountId=5b10ac8d82e05b22cc7d4ef5`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

{
  "key": "issue.support",
  "value": {
    "system.conversation.id": "b1bf38be-5e94-4b40-a3b8-9278735ee1e6",
    "system.support.time": "1m"
  }
}

PUT

Set user property

Sets the value of a user's property. Use this resource to store custom data against a user.

Note: This operation does not access the user properties created and maintained in Jira.

Permissions required:

Administer Jira global permission, to set a property on any user.
Access to Jira, to set a property on the calling user's record.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:write:jira-work

Granular:write:user.property:jira

Connect app scope required: WRITE

Request

Path parameters

propertyKey

string

Required

Query parameters

accountId

string

userKey

string

username

string

Request bodyapplication/json

The value of the property. The value has to be a valid, non-empty JSON value. The maximum length of the property value is 32768 bytes.

any

Responses

Returned if the user property is updated.

application/json

any

PUT/rest/api/3/user/properties/{propertyKey}

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

var bodyData = `{}`;

const response = await api.asUser().requestJira(route`/rest/api/3/user/properties/{propertyKey}?accountId=5b10ac8d82e05b22cc7d4ef5`, {
  method: 'PUT',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: bodyData
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

DEL

Delete user property

Deletes a property from a user.

Note: This operation does not access the user properties created and maintained in Jira.

Permissions required:

Administer Jira global permission, to delete a property from any user.
Access to Jira, to delete a property from the calling user's record.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:write:jira-work

Granular:delete:user.property:jira

Connect app scope required: DELETE

Request

Path parameters

propertyKey

string

Required

Query parameters

accountId

string

userKey

string

username

string

Responses

Returned if the user property is deleted.

DEL/rest/api/3/user/properties/{propertyKey}

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asUser().requestJira(route`/rest/api/3/user/properties/{propertyKey}?accountId=5b10ac8d82e05b22cc7d4ef5`, {
  method: 'DELETE'
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.text());