---
title: "Switch temporary credential roles"
slug: "switch-role"
tags: ["Secure Token Service"]
updated: 2026-09-17T10:05:35Z
published: 2026-09-17T10:05:35Z
canonical: "api.ncloud-docs.com/switch-role"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Switch temporary credential roles

Available in Classic and VPC

Create temporary credentials with the role switched by granting the switchRole policy.

Note

For more information about role switching and the switchRole policy, see [Manage policies and roles](https://guide.ncloud-docs.com/docs/en/subaccount-policy-role) of the Sub Account user guide.

## Request

This section describes the request format. The method and URI are as follows:

| Method | URI |
| --- | --- |
| POST | /api/v1/switch-role |

### Request headers

For information about the headers common to all Secure Token Service APIs, see [Secure Token Service request headers](/docs/en/management-sts#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94).

### Request body

You can include the following data in the body of your request:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `roleNrn` | String | Required | NRN of the role to switch |
| `durationSec` | Integer | Optional | Access key validity time (second) - 600-43200 (default: 3600) |
| `serialNumber` | String | Optional | Serial number - OTP device NRN \| MFA serial number |
| `tokenCode` | Integer | Optional | OTP verification code |

### Request example

The request example is as follows:

```
curl --location --request POST 'https://sts.apigw.ntruss.com/api/v1/switch-role' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json' \
--data '{
	"roleNrn": "nrn:PUB:IAM::*****:Role/******************"
}'
```

## Response

This section describes the response format.

### Response body

The response body includes the following data:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `switchedRole` | String | - | NRN of the switched role |
| `credentials` | Object | - | Role switch result |
| `credentials.accessKey` | String | - | Access Key |
| `credentials.keySecret` | String | - | Secret Key |
| `credentials.createTime` | String | - | Creation date - ISO 8601 format |
| `credentials.expireTime` | String | - | Expiration date - ISO 8601 format |
| `credentials.useMfa` | Boolean | - | MFA authentication - `true` \| `false` - `true`: Authenticate - `false`: No authentication |

### Response status codes

For information about the HTTP status codes common to all Secure Token Service APIs, see [Secure Token Service response status codes](/docs/en/management-sts#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C).

### Response example

The response example is as follows:

```
{
  "switchedRole": "nrn:PUB:IAM::*****:Role/******************",
  "credentials": {
    "accessKey": "ncp_iam_***************",
    "keySecret": "ncp_iam_**********************",
    "createTime": "2024-10-10T16:58:28Z",
    "expireTime": "2024-10-10T17:58:28Z",
    "useMfa": false
  }
}
```