Share via

Api Tokens - Create

  • Reference
Service:
IoT Central
API Version:
2022-07-31

Create a new API token in the application to use in the IoT Central public API. The token value will be returned in the response, and won't be returned again in subsequent requests.

PUT https://{subdomain}.{baseDomain}/api/apiTokens/{tokenId}?api-version=2022-07-31

URI Parameters

Name In Required Type Description
baseDomain
 path True

string

The base domain for all Azure IoT Central service requests.
subdomain
 path True

string

The application subdomain.
tokenId
 path True

string

Unique ID for the API token.
api-version
 query True

string

The version of the API being called.

Request Body

Name Required Type Description
roles True

RoleAssignment[]

List of role assignments that specify the permissions to access the application.
expiry

string

String-formatted date representing the time when the token expires.

Responses

Name Type Description
200 OK

ApiToken

Success
Other Status Codes

Error

An error response received from the IoT Central Service.

Headers

x-ms-error-code: string

Security

azure_auth

Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
user_impersonation impersonate your user account

Examples

Create API token

Sample request

PUT https://appsubdomain.azureiotcentral.com/api/apiTokens/testtoken?api-version=2022-07-31

{
  "roles": [
    {
      "role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
    },
    {
      "role": "c495eb57-eb18-489e-9802-62c474e5645c",
      "organization": "seattle"
    }
  ]
}

Sample response

Status code:
200 
{
  "id": "testtoken",
  "roles": [
    {
      "role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
    },
    {
      "role": "c495eb57-eb18-489e-9802-62c474e5645c",
      "organization": "seattle"
    }
  ],
  "expiry": "2020-10-18T18:30:40.227Z",
  "token": "SharedAccessSignature sr=..."
}

Definitions

Name Description
ApiToken

The API access token definition.
Error

The response error definition.
ErrorDetails

The detail information of the error.
RoleAssignment

The role assignment definition.

ApiToken

The API access token definition.

Name Type Description
expiry

string

String-formatted date representing the time when the token expires.
id

string

Unique ID of the API token.
roles

RoleAssignment[]

List of role assignments that specify the permissions to access the application.
token

string

Value of the API token.

Error

The response error definition.

Name Type Description
error

ErrorDetails

Error details for current request.

ErrorDetails

The detail information of the error.

Name Type Description
code

string

Error code.
message

string

Error message details.
requestId

string

Correlation Id for current request.
time

string

The time that error request failed.

RoleAssignment

The role assignment definition.

Name Type Description
organization

string

ID of the organization for this role assignment.
role

string

ID of the role for this role assignment.