{"_id":"56795de3ade8221700923d2c","category":{"_id":"55dd9f4dab0e4d210045aaea","pages":["55dd9f4dab0e4d210045aaeb","55e96008ffba3323004216ea","55e96030e5d0c623003ed885","55e97a097f564237001d5b80","56795de3ade8221700923d2c","56797b1584397c0d00fe13ea"],"version":"55dd9f4dab0e4d210045aae9","__v":6,"project":"55dd9f2e0efd5821000d54d9","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-08-26T11:12:47.544Z","from_sync":false,"order":0,"slug":"overview","title":"Overview"},"project":"55dd9f2e0efd5821000d54d9","__v":15,"user":"55dd9841cafe7221002a4c62","parentDoc":null,"version":{"_id":"55dd9f4dab0e4d210045aae9","__v":39,"project":"55dd9f2e0efd5821000d54d9","createdAt":"2015-08-26T11:13:17.024Z","releaseDate":"2015-08-26T11:13:17.024Z","categories":["55dd9f4dab0e4d210045aaea","55ddb5fa9067202b00ddff6f","55e0472c6bad670d0081f213","55e04764a44fae0d00214671","55e047a9a44fae0d00214672","55e047b258c5460d0076a9a7","55e95e337fc27b2d00d32cf2","55e979bda7ca823900ad549a","55edb8c18dcb210d0056900b","55f0365c8563861700a33765","55f03677d58f9b1900acf996","55f036938eeefc23001ea5de","55f036a38563861700a33767","55f036c08563861700a33769","55f036d02911b72100482cd7","55f036e92911b72100482cd9","55f036fa8563861700a3376b","55f0370ee507711900e58c69","55f0371df6101b1900c70700","55f0374f2911b72100482cdb","55f0375e2911b72100482cdc","560eb0f659cb8d0d0015cd52","560eb25239fad419002ae1e0","561fb64d4d67490d00804b2a","562b9f775a39cd0d009aff22","562ba0505a39cd0d009aff23","562ba149d56bc30d00f0cb18","562ba595f68a5f0d007b1f3b","562ba78fd56bc30d00f0cb1b","562ba8b95a39cd0d009aff27","562baadf6562140d001501d2","562bab37f68a5f0d007b1f3d","562bc1bf9ebc950d000f7523","562bc99ced4bea0d00c11dfa","562bd29c1b98640d00714520","562bd5875a39cd0d009aff60","562bdfabff2da50d002c0aaf","562be0bd5a39cd0d009aff75","57a0b476d8313e1900454439"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-12-22T14:27:47.973Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"## Overview\n\ndotmailer uses OAuth 2.0 to provide 'single sign-on'. Single sign-on provides the means for a dotmailer user to log into their account just once, removing the need for them to constantly re-enter their credentials. When they wish to use their dotmailer account, they just have to click a specially crafted URL.\n\nOAuth 2.0 is a relatively simple protocol built on top of HTTP. There are five key stages in using it to provide single sign-on for a user’s dotmailer account:\n\n**1. Registering with dotmailer**\nOnly pre-registered clients may call the dotmailer OAuth 2.0 API.\n**2. Obtaining an authorisation code**\nWhen you want to be able to provide a user with single sign-on, you must first get the user’s authorisation to provide this service. If the user consents, an authorisation code is issued.\n**3. Exchanging an authorisation code for an access and refresh token**\nThe authorisation code is then exchanged for an access token and refresh token. Access tokens are used to log a user in to dotmailer, while refresh tokens are used to obtain more access tokens in the future.\n**4. Using an access token to log a user in**\nThe access token is appended to a URL for a dotmailer page; “create a new campaign”, “view your campaigns’ reports”, etc. This URL may be embedded in your web application, allowing a user to click the link and log in to their dotmailer account.\n**5. Obtaining more access tokens**\nFor security reasons, access tokens have short lives. You can create new access tokens using the refresh token issued in stage 3.\n\nIn the following sections, each stage will be examined in detail.\n\n## Registering with dotmailer\n\nTo register to use OAuth you will need to be on an Enterprise licence and to contact your account manager. When you register with dotmailer for use of the OAuth 2.0 service, you must provide a URL that will be used to receive authorisation responses. This is known as the **redirect URI**. The redirect URI must:\n\n  * Use the HTTPS scheme (http://example.com/callback is not allowed)\n  * Not contain a fragment (https://example.com/callback#fragment) is not allowed\n  \nWhen registration is complete you will receive:\n\n1. **A client ID** - a string that is used to identify you when making authorisation and tokens requests.\n2. **A client secret** - a string that is used to authenticate you when making token requests. This must be kept secret.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note for any accounts with child accounts\",\n  \"body\": \"Registering your main dotmailer account for OAuth access will by default enable all your child accounts for OAuth authentication. Any new accounts just need to complete the initial authorisation phase before obtaining an access and refresh token.\\n\\n**You will need to have an SSL certificate for your application domain.** If you do not have one already, please speak to your account manager about buying one.\"\n}\n[/block]\n## Obtaining an authorisation code\n\nAuthorisation codes are the starting block in providing single sign-on for a user - you send a request to the dotmailer OAuth 2.0 API indicating that you would like to provide single sign-on for a user. The user is then prompted to log in (signifying their acceptance for your application to provide single sign-on authentication) and once their credentials have been validated, an authorisation code is sent to your redirect URI.\n\nThis code represents a user’s permission to provide single sign-on for them. It is short lived (it will expire in 10 minutes) so should be exchanged for an access and refresh token as soon as possible.\n\n**Sending the authorisation request**\n\nRequests for authorisation codes are sent using a HTTP GET request to https://r1-app.dotmailer.com/OAuth2/authorise.aspx (or with the account's appropriate region URL), with the parameters below added as query string parameters. SSL must be used and plain HTTP connections are refused.\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"client_id\",\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Required\",\n    \"h-2\": \"Values (case sensitive)\",\n    \"h-3\": \"Description\",\n    \"0-1\": \"Yes\",\n    \"0-2\": \"Your registered client ID\",\n    \"0-3\": \"The ID of the OAuth 2.0 making the request.\",\n    \"1-0\": \"redirect_uri\",\n    \"1-1\": \"Yes\",\n    \"1-2\": \"Your registered redirect URI\",\n    \"1-3\": \"Determines where the response will be sent. Must match the redirect URI registered with the specified client ID. Values should be URL encoded.\",\n    \"2-0\": \"response_type\",\n    \"2-1\": \"Yes\",\n    \"2-2\": \"code\",\n    \"2-3\": \"The type of response. Currently only ‘code’ is supported.\",\n    \"3-0\": \"scope\",\n    \"3-3\": \"Indicates the scope of access your application is requesting. Currently only ‘Account’ is supported, which translates to complete control over an account.\",\n    \"4-0\": \"state\",\n    \"4-1\": \"No\",\n    \"3-1\": \"Yes\",\n    \"3-2\": \"Account\",\n    \"4-2\": \"Any string\",\n    \"4-3\": \"Any value present in this field will be returned exactly as it was found in the authorisation response.\\nThis allows you to maintain state between pages in your app that make authorisation requests and the page that receives the response.\"\n  },\n  \"cols\": 4,\n  \"rows\": 5\n}\n[/block]\n## Handling the response\n\nIf the authorisation request is well formed and successful, the authorisation server will redirect to the redirect URI supplied in the redirect_uri parameter.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"code\",\n    \"1-0\": \"state\",\n    \"0-1\": \"The authorisation code.\",\n    \"1-1\": \"If the state parameter was present in the authorisation request, holds the value passed in the request.\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n**Example request and response**\n\nThe following is an example of an authorisation request for a client with the identifier QVNY867m2DQozogTJfUmqA%3D%3D and the redirect URI https://testhost.com/callback:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://r1-app.dotmailer.com/OAuth2/authorise.aspx?redirect_uri=https%3A%2F%2Ftesthost.com%2Fcallback&client_id=QVNY867m2DQozogTJfUmqA%3D%3D&scope=Account&state=somevalue&response_type=code\",\n      \"language\": \"text\",\n      \"name\": \" \"\n    }\n  ]\n}\n[/block]\nThis will result in a HTTP redirect to this URI:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://testhost.com/callback?code=6U0XQpAgGC4WbWM2c7a5SQ%3D%3D&state=somevalue\",\n      \"language\": \"text\",\n      \"name\": \" \"\n    }\n  ]\n}\n[/block]\nThe authorisation code (6U0XQpAgGC4WbWM2c7a5SQ%3D%3D) can be found in the code parameter. Note that the state parameter holds the same value as it did in the authorisation request.\n\nNote that the authorisation code ends in ‘%3D%3D’ because it has already been URL encoded.\n\n## Exchanging an authorisation code for an access and refresh token\n\nOnce you have your authorisation code, you can exchange it for an access and refresh token.\n\n  * **Access tokens** are included in requests for a user’s dotmailer private resources, signing in the associated user into dotmailer. They are short lived (the default expiry time is an hour).\n  * **Refresh tokens** are used to generate more access tokens. When an access token expires, you may use the refresh token to generate a new access token without having to obtain a new authorisation code (see the [Obtaining more access tokens](#section-obtaining-more-access-tokens) section).\n\n**Sending the token request**\n\nToken requests are made using a HTTP POST request to https://r1-app.dotmailer.com/OAuth2/Tokens.ashx (or with the account's appropriate region URL), where the body of the request contains the parameters in the 'application/x-www-form-urlencoded' format. SSL must be used and plain HTTP connections are rejected.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Required\",\n    \"h-2\": \"Values (case sensitive)\",\n    \"h-3\": \"Description\",\n    \"0-0\": \"client_id\",\n    \"1-0\": \"redirect_uri\",\n    \"2-0\": \"client_secret\",\n    \"3-0\": \"code\",\n    \"4-0\": \"grant_type\",\n    \"5-0\": \"test_mode\",\n    \"0-1\": \"Yes\",\n    \"1-1\": \"Yes\",\n    \"2-1\": \"Yes\",\n    \"3-1\": \"Yes\",\n    \"4-1\": \"Yes\",\n    \"5-1\": \"No\",\n    \"0-2\": \"Your registered client ID\",\n    \"1-2\": \"Your registered redirect URI\",\n    \"2-2\": \"Your registered client secret\",\n    \"3-2\": \"An authorisation code\",\n    \"4-2\": \"authorization_code\",\n    \"5-2\": \"true or false\",\n    \"0-3\": \"The ID of the OAuth 2.0 making the request.\",\n    \"1-3\": \"Must match the redirect URI registered with the specified client ID. Values should be URL encoded.\",\n    \"2-3\": \"The pre-shared client secret, used to authenticate your application when making the token request.\",\n    \"3-3\": \"An authorisation code that was issued to your application.\",\n    \"5-3\": \"If true, the issued access token will have a very short life span (about 20 seconds). Useful for testing token expiry.\"\n  },\n  \"cols\": 4,\n  \"rows\": 6\n}\n[/block]\n**Handling the response**\n\nThe response returned is a JSON-encoded object. On success, the object will contain the following fields:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"token_type\",\n    \"1-0\": \"expires_in\",\n    \"2-0\": \"access_token\",\n    \"3-0\": \"refresh_token\",\n    \"0-1\": \"The authentication mechanism that the access token uses. Will always return bearer.\",\n    \"1-1\": \"The time, in seconds, that the access token will expire in.\",\n    \"2-1\": \"The access token ID.\",\n    \"3-1\": \"The refresh token ID.\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\nIf an error occurred, the object will contain the following fields:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"error\",\n    \"1-0\": \"error_description\",\n    \"0-1\": \"The type of error that occurred. See the [IETF OAuth 2.0 draft spec, version 25 section 5.2]( http://tools.ietf.org/html/draft-ietf-oauth-v2-25#section-5.2) for a detailed list of the type of errors and their descriptions.\",\n    \"1-1\": \"A descriptive error message that explains the error field and what should be done to fix the issue.\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n**Example request and response**\n\nThe following is an example of a token request, using the authorisation code value 5RFR3oRx5yF3I5LIbZ1g7w%3d%3d. Certain HTTP headers have been omitted for brevity:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST https://r1-app.dotmailer.com/OAuth2/Tokens.ashx HTTP/1.1\\nContent-Type: application/x-www-form-urlencoded\\nclient_id=QVNY867m2DQozogTJfUmqA%3D%3D&\\nredirect_uri=https%3a%2f%2flocalhost%3a10999%2fcallback.aspx\\n&client_secret=SndpTndiSlhRawAAAAAAAA%3D%3D&\\n&grant_type=authorization_code\",\n      \"language\": \"text\",\n      \"name\": \" \"\n    }\n  ]\n}\n[/block]\nThis will generate the JSON-encoded response:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"HTTP/1.1 200 OK\\nContent-Type: application/json;charset=UTF-8\\n{\\\"access_token\\\":\\\"SJDXSNANPMTaUbIKYFHdYQ%3D%3D\\\",\\\"token_type\\\":\\\"bearer\\\",\\\"expires_in\\\":3600,\\\"refresh_token\\\":\\\"9OjH6t1-ugikUduoNBcr-g%3D%3D\\\"}\",\n      \"language\": \"text\",\n      \"name\": \" \"\n    }\n  ]\n}\n[/block]\nNote that the access token ends in ‘%3D%3D’ because it has already been URL encoded.\n\n## Using an access token to log a user in\n\n**Forming a single sign-on URL**\n\nOnce you have successfully received an access token, you can use it to log a user in. Access tokens are appended to requests for dotmailer pages using the oauthtoken query string parameter. Generally, any URL generated by the dotmailer website can have the oauthtoken query string parameter attached and it will authenticate a user.\n\nTo allow a user to view the reporting section of the dotmailer site which has the URL http://r1-app.dotmailer.com/Reporting/ and given the access token 'testokenval', the resulting URL would look like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://r1-app.dotmailer.com/Reporting/?oauthtoken=testtokenval \",\n      \"language\": \"text\",\n      \"name\": \" \"\n    }\n  ]\n}\n[/block]\nIf the access token has expired, the user is prompted to log in (as they normally would).\n\n**Beware of tokens expiring and slow users!**\n\nWhen generating single sign-on URLs, it is not recommended that you insert them directly into your pages. Tokens may not have expired at page generation time but content caching or 'slow' users may mean the access token expires before the user clicks on the hyperlink.\n\nInstead, it is recommended that single sign-on URLs are created exactly when they are needed - when a user of your application has signified that they wish to log into their dotmailer account (an HTTP redirect can accomplish this).\n\n## Obtaining more access tokens\n\nAccess tokens will expire in a short period of time for security reasons. When you wish to acquire a new access token, you can issue a refresh token request.\n\n**Sending the refresh token request**\n\nRefresh token requests are made in a very similar manner to token requests. The request is made using a HTTP POST request to https://r1-app.dotmailer.com/OAuth2/Tokens.ashx (or with the account's appropriate region URL), over SSL and with the body of the request containing the parameters in the 'application/x-www-form-urlencoded' format.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Required\",\n    \"h-2\": \"Values (case sensitive)\",\n    \"h-3\": \"Description\",\n    \"0-0\": \"client_id\",\n    \"1-0\": \"client_secret\",\n    \"2-0\": \"refresh_token\",\n    \"3-0\": \"grant_type\",\n    \"4-0\": \"test_mode\",\n    \"0-1\": \"Yes\",\n    \"1-1\": \"Yes\",\n    \"2-1\": \"Yes\",\n    \"3-1\": \"Yes\",\n    \"4-1\": \"No\",\n    \"0-2\": \"Your registered client ID\",\n    \"1-2\": \"Your registered client secret\",\n    \"2-2\": \"A refresh token\",\n    \"3-2\": \"refresh_token\",\n    \"4-2\": \"true or false\",\n    \"0-3\": \"The ID of the OAuth 2.0 making the request.\",\n    \"1-3\": \"The pre-shared client secret, used to authenticate your application when making the token request.\",\n    \"2-3\": \"A refresh token that was issued to your application.\",\n    \"4-3\": \"If true, the issued access token will have a very short life span (about 20 seconds). Useful for testing token expiry.\"\n  },\n  \"cols\": 4,\n  \"rows\": 5\n}\n[/block]\n**Handling the response**\n\nThe response returned is a JSON-encoded object. On success, the object will contain the following fields:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"token_type\",\n    \"1-0\": \"expires_in\",\n    \"2-0\": \"access_token\",\n    \"0-1\": \"The authentication mechanism that the access token uses. Will always return bearer.\",\n    \"1-1\": \"The time in seconds that the access token will expire in.\",\n    \"2-1\": \"The access token ID.\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n## Useful external resources\n\nThe following links might be useful in understanding OAuth 2.0 and the dotmailer implementation.\n\n  * [IETF OAuth 2.0 draft spec, version 25](http://tools.ietf.org/html/draft-ietf-oauth-v2-25). The draft specification and version the dotmailer implementation was based on.\n  * [Google OAuth 2.0 API docs](https://developers.google.com/identity/protocols/OAuth2). While not directly related to the dotmailer implementation, it gives a good overview of the OAuth 2.0 protocol, complete with some lovely diagrams.","excerpt":"","slug":"using-oauth-20-with-dotmailer","type":"basic","title":"Using OAuth 2.0 with dotmailer"}

Using OAuth 2.0 with dotmailer


## Overview dotmailer uses OAuth 2.0 to provide 'single sign-on'. Single sign-on provides the means for a dotmailer user to log into their account just once, removing the need for them to constantly re-enter their credentials. When they wish to use their dotmailer account, they just have to click a specially crafted URL. OAuth 2.0 is a relatively simple protocol built on top of HTTP. There are five key stages in using it to provide single sign-on for a user’s dotmailer account: **1. Registering with dotmailer** Only pre-registered clients may call the dotmailer OAuth 2.0 API. **2. Obtaining an authorisation code** When you want to be able to provide a user with single sign-on, you must first get the user’s authorisation to provide this service. If the user consents, an authorisation code is issued. **3. Exchanging an authorisation code for an access and refresh token** The authorisation code is then exchanged for an access token and refresh token. Access tokens are used to log a user in to dotmailer, while refresh tokens are used to obtain more access tokens in the future. **4. Using an access token to log a user in** The access token is appended to a URL for a dotmailer page; “create a new campaign”, “view your campaigns’ reports”, etc. This URL may be embedded in your web application, allowing a user to click the link and log in to their dotmailer account. **5. Obtaining more access tokens** For security reasons, access tokens have short lives. You can create new access tokens using the refresh token issued in stage 3. In the following sections, each stage will be examined in detail. ## Registering with dotmailer To register to use OAuth you will need to be on an Enterprise licence and to contact your account manager. When you register with dotmailer for use of the OAuth 2.0 service, you must provide a URL that will be used to receive authorisation responses. This is known as the **redirect URI**. The redirect URI must: * Use the HTTPS scheme (http://example.com/callback is not allowed) * Not contain a fragment (https://example.com/callback#fragment) is not allowed When registration is complete you will receive: 1. **A client ID** - a string that is used to identify you when making authorisation and tokens requests. 2. **A client secret** - a string that is used to authenticate you when making token requests. This must be kept secret. [block:callout] { "type": "info", "title": "Note for any accounts with child accounts", "body": "Registering your main dotmailer account for OAuth access will by default enable all your child accounts for OAuth authentication. Any new accounts just need to complete the initial authorisation phase before obtaining an access and refresh token.\n\n**You will need to have an SSL certificate for your application domain.** If you do not have one already, please speak to your account manager about buying one." } [/block] ## Obtaining an authorisation code Authorisation codes are the starting block in providing single sign-on for a user - you send a request to the dotmailer OAuth 2.0 API indicating that you would like to provide single sign-on for a user. The user is then prompted to log in (signifying their acceptance for your application to provide single sign-on authentication) and once their credentials have been validated, an authorisation code is sent to your redirect URI. This code represents a user’s permission to provide single sign-on for them. It is short lived (it will expire in 10 minutes) so should be exchanged for an access and refresh token as soon as possible. **Sending the authorisation request** Requests for authorisation codes are sent using a HTTP GET request to https://r1-app.dotmailer.com/OAuth2/authorise.aspx (or with the account's appropriate region URL), with the parameters below added as query string parameters. SSL must be used and plain HTTP connections are refused. [block:parameters] { "data": { "0-0": "client_id", "h-0": "Parameter", "h-1": "Required", "h-2": "Values (case sensitive)", "h-3": "Description", "0-1": "Yes", "0-2": "Your registered client ID", "0-3": "The ID of the OAuth 2.0 making the request.", "1-0": "redirect_uri", "1-1": "Yes", "1-2": "Your registered redirect URI", "1-3": "Determines where the response will be sent. Must match the redirect URI registered with the specified client ID. Values should be URL encoded.", "2-0": "response_type", "2-1": "Yes", "2-2": "code", "2-3": "The type of response. Currently only ‘code’ is supported.", "3-0": "scope", "3-3": "Indicates the scope of access your application is requesting. Currently only ‘Account’ is supported, which translates to complete control over an account.", "4-0": "state", "4-1": "No", "3-1": "Yes", "3-2": "Account", "4-2": "Any string", "4-3": "Any value present in this field will be returned exactly as it was found in the authorisation response.\nThis allows you to maintain state between pages in your app that make authorisation requests and the page that receives the response." }, "cols": 4, "rows": 5 } [/block] ## Handling the response If the authorisation request is well formed and successful, the authorisation server will redirect to the redirect URI supplied in the redirect_uri parameter. [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "0-0": "code", "1-0": "state", "0-1": "The authorisation code.", "1-1": "If the state parameter was present in the authorisation request, holds the value passed in the request." }, "cols": 2, "rows": 2 } [/block] **Example request and response** The following is an example of an authorisation request for a client with the identifier QVNY867m2DQozogTJfUmqA%3D%3D and the redirect URI https://testhost.com/callback: [block:code] { "codes": [ { "code": "https://r1-app.dotmailer.com/OAuth2/authorise.aspx?redirect_uri=https%3A%2F%2Ftesthost.com%2Fcallback&client_id=QVNY867m2DQozogTJfUmqA%3D%3D&scope=Account&state=somevalue&response_type=code", "language": "text", "name": " " } ] } [/block] This will result in a HTTP redirect to this URI: [block:code] { "codes": [ { "code": "https://testhost.com/callback?code=6U0XQpAgGC4WbWM2c7a5SQ%3D%3D&state=somevalue", "language": "text", "name": " " } ] } [/block] The authorisation code (6U0XQpAgGC4WbWM2c7a5SQ%3D%3D) can be found in the code parameter. Note that the state parameter holds the same value as it did in the authorisation request. Note that the authorisation code ends in ‘%3D%3D’ because it has already been URL encoded. ## Exchanging an authorisation code for an access and refresh token Once you have your authorisation code, you can exchange it for an access and refresh token. * **Access tokens** are included in requests for a user’s dotmailer private resources, signing in the associated user into dotmailer. They are short lived (the default expiry time is an hour). * **Refresh tokens** are used to generate more access tokens. When an access token expires, you may use the refresh token to generate a new access token without having to obtain a new authorisation code (see the [Obtaining more access tokens](#section-obtaining-more-access-tokens) section). **Sending the token request** Token requests are made using a HTTP POST request to https://r1-app.dotmailer.com/OAuth2/Tokens.ashx (or with the account's appropriate region URL), where the body of the request contains the parameters in the 'application/x-www-form-urlencoded' format. SSL must be used and plain HTTP connections are rejected. [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Required", "h-2": "Values (case sensitive)", "h-3": "Description", "0-0": "client_id", "1-0": "redirect_uri", "2-0": "client_secret", "3-0": "code", "4-0": "grant_type", "5-0": "test_mode", "0-1": "Yes", "1-1": "Yes", "2-1": "Yes", "3-1": "Yes", "4-1": "Yes", "5-1": "No", "0-2": "Your registered client ID", "1-2": "Your registered redirect URI", "2-2": "Your registered client secret", "3-2": "An authorisation code", "4-2": "authorization_code", "5-2": "true or false", "0-3": "The ID of the OAuth 2.0 making the request.", "1-3": "Must match the redirect URI registered with the specified client ID. Values should be URL encoded.", "2-3": "The pre-shared client secret, used to authenticate your application when making the token request.", "3-3": "An authorisation code that was issued to your application.", "5-3": "If true, the issued access token will have a very short life span (about 20 seconds). Useful for testing token expiry." }, "cols": 4, "rows": 6 } [/block] **Handling the response** The response returned is a JSON-encoded object. On success, the object will contain the following fields: [block:parameters] { "data": { "h-0": "Field", "h-1": "Description", "0-0": "token_type", "1-0": "expires_in", "2-0": "access_token", "3-0": "refresh_token", "0-1": "The authentication mechanism that the access token uses. Will always return bearer.", "1-1": "The time, in seconds, that the access token will expire in.", "2-1": "The access token ID.", "3-1": "The refresh token ID." }, "cols": 2, "rows": 4 } [/block] If an error occurred, the object will contain the following fields: [block:parameters] { "data": { "h-0": "Field", "h-1": "Description", "0-0": "error", "1-0": "error_description", "0-1": "The type of error that occurred. See the [IETF OAuth 2.0 draft spec, version 25 section 5.2]( http://tools.ietf.org/html/draft-ietf-oauth-v2-25#section-5.2) for a detailed list of the type of errors and their descriptions.", "1-1": "A descriptive error message that explains the error field and what should be done to fix the issue." }, "cols": 2, "rows": 2 } [/block] **Example request and response** The following is an example of a token request, using the authorisation code value 5RFR3oRx5yF3I5LIbZ1g7w%3d%3d. Certain HTTP headers have been omitted for brevity: [block:code] { "codes": [ { "code": "POST https://r1-app.dotmailer.com/OAuth2/Tokens.ashx HTTP/1.1\nContent-Type: application/x-www-form-urlencoded\nclient_id=QVNY867m2DQozogTJfUmqA%3D%3D&\nredirect_uri=https%3a%2f%2flocalhost%3a10999%2fcallback.aspx\n&client_secret=SndpTndiSlhRawAAAAAAAA%3D%3D&\n&grant_type=authorization_code", "language": "text", "name": " " } ] } [/block] This will generate the JSON-encoded response: [block:code] { "codes": [ { "code": "HTTP/1.1 200 OK\nContent-Type: application/json;charset=UTF-8\n{\"access_token\":\"SJDXSNANPMTaUbIKYFHdYQ%3D%3D\",\"token_type\":\"bearer\",\"expires_in\":3600,\"refresh_token\":\"9OjH6t1-ugikUduoNBcr-g%3D%3D\"}", "language": "text", "name": " " } ] } [/block] Note that the access token ends in ‘%3D%3D’ because it has already been URL encoded. ## Using an access token to log a user in **Forming a single sign-on URL** Once you have successfully received an access token, you can use it to log a user in. Access tokens are appended to requests for dotmailer pages using the oauthtoken query string parameter. Generally, any URL generated by the dotmailer website can have the oauthtoken query string parameter attached and it will authenticate a user. To allow a user to view the reporting section of the dotmailer site which has the URL http://r1-app.dotmailer.com/Reporting/ and given the access token 'testokenval', the resulting URL would look like this: [block:code] { "codes": [ { "code": "https://r1-app.dotmailer.com/Reporting/?oauthtoken=testtokenval ", "language": "text", "name": " " } ] } [/block] If the access token has expired, the user is prompted to log in (as they normally would). **Beware of tokens expiring and slow users!** When generating single sign-on URLs, it is not recommended that you insert them directly into your pages. Tokens may not have expired at page generation time but content caching or 'slow' users may mean the access token expires before the user clicks on the hyperlink. Instead, it is recommended that single sign-on URLs are created exactly when they are needed - when a user of your application has signified that they wish to log into their dotmailer account (an HTTP redirect can accomplish this). ## Obtaining more access tokens Access tokens will expire in a short period of time for security reasons. When you wish to acquire a new access token, you can issue a refresh token request. **Sending the refresh token request** Refresh token requests are made in a very similar manner to token requests. The request is made using a HTTP POST request to https://r1-app.dotmailer.com/OAuth2/Tokens.ashx (or with the account's appropriate region URL), over SSL and with the body of the request containing the parameters in the 'application/x-www-form-urlencoded' format. [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Required", "h-2": "Values (case sensitive)", "h-3": "Description", "0-0": "client_id", "1-0": "client_secret", "2-0": "refresh_token", "3-0": "grant_type", "4-0": "test_mode", "0-1": "Yes", "1-1": "Yes", "2-1": "Yes", "3-1": "Yes", "4-1": "No", "0-2": "Your registered client ID", "1-2": "Your registered client secret", "2-2": "A refresh token", "3-2": "refresh_token", "4-2": "true or false", "0-3": "The ID of the OAuth 2.0 making the request.", "1-3": "The pre-shared client secret, used to authenticate your application when making the token request.", "2-3": "A refresh token that was issued to your application.", "4-3": "If true, the issued access token will have a very short life span (about 20 seconds). Useful for testing token expiry." }, "cols": 4, "rows": 5 } [/block] **Handling the response** The response returned is a JSON-encoded object. On success, the object will contain the following fields: [block:parameters] { "data": { "h-0": "Field", "h-1": "Description", "0-0": "token_type", "1-0": "expires_in", "2-0": "access_token", "0-1": "The authentication mechanism that the access token uses. Will always return bearer.", "1-1": "The time in seconds that the access token will expire in.", "2-1": "The access token ID." }, "cols": 2, "rows": 3 } [/block] ## Useful external resources The following links might be useful in understanding OAuth 2.0 and the dotmailer implementation. * [IETF OAuth 2.0 draft spec, version 25](http://tools.ietf.org/html/draft-ietf-oauth-v2-25). The draft specification and version the dotmailer implementation was based on. * [Google OAuth 2.0 API docs](https://developers.google.com/identity/protocols/OAuth2). While not directly related to the dotmailer implementation, it gives a good overview of the OAuth 2.0 protocol, complete with some lovely diagrams.