https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/sessions/startThe /sessions/start endpoint starts a basemap session and returns the values for the startTime, endTime, styleFamily, and sessionToken.
The general steps to start and manage a session are:
- Set the
styleFamilyparameter to retrieve eitherarcgisoropenstyles. - Supply an access token that has
the
premium:user:basemapsprivilege either in thetokenparameter or in the request header. - Display a basemap using the
sessionTokenstring returned in the response. - Track when the session will expire by using the
startTimeandendTimevalues that are also returned in the response.
If you need to continue accessing basemaps beyond the end of the session,
start a new basemap session before the endTime has elapsed using your
original access token.
Note:
- Basemap sesions are only available for developers with an ArcGIS Location Platform account.
- A session token can access either styles from the ArcGIS or Open style families.
- Each session token is valid for up to 12 hours and is limited to the duration for which your application is running.
- An expired session token cannot be used to start a new session.
- A session token is specfic to the Basemap Styles service. You cannot use this session token to access other services.
To learn how to use a basemap session, go to Mapping and location services > Mapping > Basemap usage.
Query parameters
| Name | Type | Required | Default value | Description |
|---|---|---|---|---|
token | string | | The authentication token, used to access the Basemap styles service. | |
f | string | json | An optional parameter to specify the format in which the response is given. It can either be json or pjson. | |
styleFamily | SessionStyleFamily | | A family of basemaps styles. | |
durationSeconds | integer(int64) | 43200 | An optional parameter to specify the session duration in seconds. |
token
The authentication token, used to access the Basemap styles service.
The token parameter can be:
- an API key
- a short-lived token
- a session token generated by the
sessions/startendpoint
API keys and short-lived tokens must be created from an account with the
premium:user:basemaps
privilege.
Session tokens must be created from an ArcGIS Location Platform account
with the premium:user:basemaps privilege.
Note that session tokens cannot be used with the sessions/start
endpoint or to fetch custom styles.
Developer guide: To learn more, go to Security and authentication.
This parameter is required unless you supply an access token in the request header with one of the following keys using the "Bearer" scheme:
Authorization: Bearer <YOUR_TOKEN>X-Esri-Authorization: Bearer <YOUR_TOKEN>
f
An optional parameter to specify the format in which the response is given. It can either be json or pjson.
- Default
- json
Enumerated values
durationSeconds
An optional parameter to specify the session duration in seconds.
If not provided, the session will default to 43200 seconds (12 hours). Valid range is from 10 to 43200 seconds.
This parameter allows you to create a session with a duration that is shorter than the default session duration of 12 hours. This is useful if you want to test your application's behavior when the session token expires. A short session duration will allow you to achieve this more easily within your application's development lifecycle.
Note that each session is charged at the same amount regardless of the session duration.
- Minimum
- 10
- Maximum
- 43200
- Default
- 43200
Response status
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Response from starting a basemap session. | BasemapSession |
| 401 | Unauthorized | Authentication Error. The API key or token is missing, invalid or expired. | Error |
| 403 | Forbidden | The supplied authentication information is valid but does not have permission to access the service. | Error |
| 5XX | **Server Error** | An error occurred on the server. | Error |
Examples
Request
# You can also use wget
curl -X GET https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/sessions/start?styleFamily=arcgis \
-H 'Authorization: Bearer <YOUR_TOKEN>'Response
{
"sessionToken": "string",
"endTime": 0,
"startTime": 0,
"styleFamily": "arcgis"
}