--- schema_version: "1" id: 60808029d8621806499324c5de6438747bcd949aa7a0ca72235f817158a9b280 title: Auth collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/references/generated-api-specs/mc_rest_auth.md canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_auth source_site: developer.salesforce.com content_type: documentation content_hash: b174cf2c7e6170e1198e8bb90eef234f36b27c56a007e6eff92ef9ff00773c14 products: - Marketing Cloud Engagement APIs and Programmatic Languages - Marketing Cloud --- Auth # Auth Obtain information about your API user, including account permissions, organization data, and API URLs. You can also use the Authentication API to obtain API access tokens, which are required to authenticate other requests to the API. This table lists the use cases that the Authentication API supports. | Supported Use Case | HTTP Verb | URI | | --- | --- | --- | | Obtain an API token | [POST](/docs/marketing/marketing-cloud/references/mc_rest_auth?meta=Obtain%2Ban%2Baccess%2Btoken) | /v2/token | | Get base URLs | [GET](/docs/marketing/marketing-cloud/references/mc_rest_auth?meta=Get%2Bbase%2Burls) | /v2/discovery | | Get user info | [GET](/docs/marketing/marketing-cloud/references/mc_rest_auth?meta=Get%2Buser%2Binfo) | /v2/userinfo | **Version:** 1.0 ## Servers * `https://{subdomain}.auth.marketingcloudapis.com` * `subdomain (default N/A) The unique API subdomain for your Marketing Cloud Engagement tenant. You can find this value in the Installed Packages section of Marketing Cloud Engagement Setup.` ## Operations ### POST Obtain an API access token `POST /v2/token` Operation ID: `getAccessToken`. Obtain a unique token that authorizes you to submit requests to the Marketing Cloud API. You can use the token for up to 20 minutes. When the token expires, request a new one to continue issuing API requests. #### Request body (required) Media type: `application/json`. Schema: `tokenRequestBody`. #### Responses * **200** A successful request returns a response that includes the API token that you must provide to execute other API operations. Media type: `application/json`. Schema: `tokenResponseBody`. _Example_ ``` { "access_token": "E0VHY1VmkiLCJjbGllbnRfaWQiOiIxb3pIcXd2ZzV2VtaUtkU0_vp8n_M3pfLtSlnFEoZL7VYZfj4-hlqscpnj3cJgmoPI...", "token_type": "Bearer", "expires_in": 1079, "scope": "offline documents_and_images_read documents_and_images_write saved_content_read saved_content_write automations_execute automations_read automations_write journeys_execute journeys_read journeys_write email_read email_send email_write push_read push_send push_write sms_read sms_send sms_write ...", "soap_instance_url": "https://{tsd}.soap.marketingcloudapis.com/", "rest_instance_url": "https://{tsd}.rest.marketingcloudapis.com/" } ``` * **401** This response indicates that Marketing Cloud wasn’t able to authorize your request. When you receive a 401 response, verify that your request contains the correct client ID, client secret, and member ID. Media type: `application/json`. Schema: `authTokenErrorResponseBody`. _Example_ ``` { "error": "invalid_client", "error_description": "Invalid client ID. Use the client ID in Marketing Cloud Installed Packages.", "error_uri": "https://developer.salesforce.com/docs" } ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that the request contains the correct endpoint URI. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 404, "message": "Not Found" } ``` ### GET Get base URLs `GET /v2/discovery` Operation ID: `getBaseUrls`. Obtain the base URLs for the Marketing Cloud Auth and REST APIs. These application-specific URLs are unique to your Marketing Cloud account and installed package. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that allows you to issue requests to the Marketing Cloud API. Replace `YOUR_ACCESS_TOKEN` with your Marketing Cloud API authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `clientId` (query, string, required) Client ID for the application. You can find the client ID in Marketing Cloud Setup > Apps > Installed Packages > {your\_package\_name}. * `resource` (query, string, required) The Marketing Cloud username to retrieve URLs for. Use the format `acct:{username}`, where `{username}` is the Marketing Cloud username. #### Responses * **200** A successful request returns a response that includes the base URLs for the Authentication and REST APIs. Media type: `application/json`. Schema: `baseUrlResponseBody`. _Example_ ``` { "subject": "acct:michele.hansley", "links": [ { "rel": "auth_instance_url", "href": "https://mctf0q1y5r3hhc20--l3kexample.auth.marketingcloudapis.com/" }, { "rel": "rest_instance_url", "href": "https://mctf0q1y5r3hhc20--l3example.rest.marketingcloudapis.com/" } ] } ``` * **400** This response indicates that Marketing Cloud wasn’t able to execute your request. This error can occur when one or more required parameters are missing in the request. Make sure that the request includes both the `client_id` and `resource` parameters and that the values of these parameters are valid. Media type: `application/json`. Schema: `authTokenErrorResponseBody`. _Example_ ``` { "error": "invalid_client", "error_description": "Invalid client ID. Use the client ID in Marketing Cloud Installed Packages.", "error_uri": "https://developer.salesforce.com/docs" } ``` * **401** This response indicates that Marketing Cloud wasn’t able to authorize your request. When you receive a 401 response, verify that you've obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `authTokenErrorResponseBody`. _Example_ ``` { "error": "unauthorized", "error_description": "Unauthorized", "error_uri": "https://developer.salesforce.com/docs" } ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that the request contains the correct endpoint URI. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 404, "message": "Not Found" } ``` ### GET Get user information `GET /v2/userinfo` Operation ID: `getUserInfo`. Retrieves information about the account and user that are associated with the access token. Supply the access token in the authorization header. User information includes the account name, email, and ID. Account information includes the member ID (MID) and enterprise ID (EID). Application information includes the base URLs for REST and SOAP APIs, redirect URLs, and scopes. Permission information includes the permission name and ID. For more information, see [REST API Permission IDs and Scopes](https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_rest_permission_scopes/rest-permissions-and-scopes.html). > **Note** > > Use a tenant-specific endpoint to retrieve user information. If you use a global endpoint, the API returns a `401 Unauthorized` error. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that allows you to issue requests to the Marketing Cloud API. Replace `YOUR_ACCESS_TOKEN` with your Marketing Cloud API authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` #### Responses * **200** A successful request returns a response that includes information about the user associated with the API access token. Media type: `application/json`. Schema: `userInfoResponseBody`. _Example_ ``` { "exp": 1691268129, "iss": "https://mc.exacttarget.com", "user": { "sub": "334455667", "name": "Michele Hansley", "preferred_username": "d8c80930-30d9-411a-8613-d4209e3de1d9", "email": "", "locale": "en-US", "zoneinfo": "America/Chicago", "timezone": { "longName": "(GMT-06:00) Central Time (US & Canada) *", "shortName": "GMT-6", "offset": -6, "dst": true } }, "organization": { "member_id": 99999, "enterprise_id": 99999, "enterprise_name": "Northern Trail Outfitters", "account_type": "core", "stack_key": "S1", "region": "NA1", "locale": "en-US", "zoneinfo": "America/Chicago", "timezone": { "longName": "(GMT-06:00) Central Time (US & Canada) *", "shortName": "GMT-6", "offset": -6, "dst": true } }, "rest": { "rest_instance_url": "https://mct3f0q1y5rhhc20--l3kexample.rest.marketingcloudapis.com/", "soap_instance_url": "https://mct3f0q1y5rhhc20--l3kexample.soap.marketingcloudapis.com/" }, "application": { "id": "06238661-8596-4abb-bd06-49e2a5465b9a", "name": "API Application", "redirectUrl": [], "appScopes": [ "campaign_read", "campaign_write" ] }, "permissions": [ { "objectTypeName": "Email", "operationName": "Create", "name": "Create", "id": 4 }, { "objectTypeName": "Email", "operationName": "View", "name": "View", "id": 5 }, { "objectTypeName": "Email", "operationName": "Update", "name": "Update", "id": 6 }, { "objectTypeName": "Email", "operationName": "Delete", "name": "Delete", "id": 7 } ] } ``` * **400** This response indicates that Marketing Cloud wasn’t able to execute your request. This error can occur when your request doesn’t include a valid API access token. Check to make sure that your request includes a token and that token is still valid. If the token is no longer valid, request a new one. Media type: `application/json`. Schema: `authTokenErrorResponseBody`. _Example_ ``` { "error": "Invalid request. Missing access token.", "error_description": "Make sure that the authorization header isn’t empty or null.", "error_uri": "https://developer.salesforce.com/docs" } ``` * **401** This response indicates that Marketing Cloud wasn’t able to authorize your request. When you receive a 401 response, verify that you've obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `authTokenErrorResponseBody`. _Example_ ``` { "error": "unauthorized", "error_description": "Unauthorized", "error_uri": "https://developer.salesforce.com/docs" } ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that the request contains the correct endpoint URI. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 404, "message": "Not Found" } ``` ## Schemas ### tokenRequestBody * `grant-type` (_string_) The type of access grant. Specify `client_credentials` as the value for this property. * `client_id` (_string_) The client ID of your Marketing Cloud account. * `client_secret` (_string_) The client secret for your Marketing Cloud account. * `account_id` (_string_) The member ID (MID) of your Marketing Cloud account. _Example_ ``` { "grant_type": "client_credentials", "client_id": "u62kv6duobqgod3t5example", "client_secret": "POiA9FJ6eWW2BuedVexample", "account_id": "99999" } ``` ### tokenResponseBody * `access_token` (_string_) The API access token. The access token contains 512 alphanumeric characters. * `token_type` (_string_) The type of token that was retrieved. This property always has the value `Bearer`. * `expires_in` (_integer_) The amount of time (in seconds) that the token remains valid. This property always has the value `1079`. * `scope` (_string_) The permissions that have been granted to your user. Multiple permission types are separated with a space. * `soap_instance_url` (_string_) The application-specific SOAP API URL. * `rest_instance_url` (_string_) The application-specific REST API URL. ### authTokenErrorResponseBody * `error` (_string_) The error message. * `error_description` (_string_) A description of the error that occurred. * `error_uri` (_string_) A link to the Salesforce developer documentation. ### httpErrorResponseBody * `documentation` (_string_) Contains a link to the [Marketing Cloud Developer Documentation page about handling REST API errors](https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm). * `errorcode` (_integer_) The HTTP error code. * `message` (_string_) The error message. ### baseUrlResponseBody * `subject` (_string_) The username of the user that you requested base URLs for. * `links` (_array of object_) An array that contains the base URLs. * `rel` (_string_) A string that indicates which API the URL applies to. Allowed values: `auth_instance_url`, `rest_instance_url`. * `href` (_string_) The application-specific URL. ### userInfoResponseBody * `exp` (_integer_) A Unix epoch timestamp that indicates when the API access token expires. * `iss` (_string_) The URL of the issuer of the API access token. * `user` (_object_) Information about the user that the access token is associated with. * `sub` (_string_) The unique ID of the user. * `name` (_string_) The user’s name. * `preferred_username` (_string_) The user’s Marketing Cloud user ID. * `email` (_string_) The email address associated with the user’s Marketing Cloud account. * `locale` (_string_) The account user’s language and country codes. * `zoneinfo` (_string_) The user’s timezone. This property uses the time zones specified in the [IANA Time Zone Database](https://www.iana.org/time-zones). * `timezone` (_object_) The user’s time zone information. * `longName` (_string_) A descriptive name for the user’s time zone. * `shortName` (_string_) A code that represents the user’s time zone offset from Coordinated Universal Time (UTC). * `offset` (_number (double)_) The offset from UTC. * `dst` (_boolean_) If this value is `true`, the user’s timezone observes daylight saving time. * `organization` (_object_) An object that contains information about the user’s organization. * `member_id` (_integer_) The Marketing Cloud account member ID (MID). * `enterprise_id` (_integer_) The Marketing Cloud top-level account enterprise ID (EID). * `enterprise_name` (_string_) The name of the top-level Marketing Cloud enterprise account. * `account_type` (_string_) The type of account. Allowed values: `core`, `reseller`, `tiered`, `enterprise`. * `stack_key` (_string_) The Marketing Cloud server instance that the account is on. * `region` (_string_) The account’s data center region. Allowed values: `NA1`, `EU1`. * `locale` (_string_) The language and country code for the top-level account. * `zoneinfo` (_string_) The organization’s timezone. This property uses the time zones specified in the [IANA Time Zone Database](https://www.iana.org/time-zones). * `timezone` (_object_) The organization’s time zone information. * `longName` (_string_) A descriptive name for the organization’s time zone. * `shortName` (_string_) A code that represents the organization’s time zone offset from Coordinated Universal Time (UTC). * `offset` (_number (double)_) The offset from UTC. * `dst` (_boolean_) If this value is `true`, the organization’s timezone observes daylight saving time. * `rest` (_object_) An object that contains API base URLs. * `rest_instance_url` (_string_) The base REST API URL. * `soap_instance_url` (_string_) The base SOAP API URL. * `application` (_object_) Information about the application. * `id` (_integer_) The application’s unique ID. * `name` (_string_) The application’s package name. * `redirectUrl` (_array of string_) The URLs for the application in the package. * `appScopes` (_array of string_) An array that lists the package scopes supported by the application. * `permissions` (_array of object_) Information about the permissions for the user. * `objectTypeName` (_string_) The type of object permission. * `operationName` (_string_) The name of the permission operation. * `name` (_string_) The permission name. * `id` (_integer_) The permission ID. For a list of permission IDs, see [REST API Permission IDs and Scopes](https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_rest_permission_scopes/rest-permissions-and-scopes.html).