{"type":"doc","content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Introduction","type":"text"}]},{"type":"paragraph","content":[{"text":"Before you can access or manipulate the ","type":"text"},{"text":"different resources that are available, you have to get a token","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"a692d371-bf12-4f51-be42-6e3843bab872"}}]},{"text":". When you are accessing or manipulating the resources, you have to provide this token in your request-header.","type":"text"}]},{"type":"paragraph","content":[{"text":"The token is needed to authenticate and authorize your calls.","type":"text"}]},{"type":"paragraph","content":[{"text":"Currently two OAuth 2.0 authorization grants is supported \"Resource owner password credentials grant\" and \"Client credentials grant\". We also provide our own Ambita authorization flow \"Trusted grant\".","type":"text"}]},{"type":"paragraph","content":[{"text":"Before you can use the Ambita-APIs including the authentication-API, you need to request a token.","type":"text"}]},{"type":"paragraph","content":[{"text":"A prerequisite for requesting a token is to obtain a client and a client secret(And possible a user and password, depending on the grant_type). In order to obtain this information is a manual process and you need to contact ","type":"text"},{"text":"Ambita Customer Service","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.ambita.com/kundeservice/"}}]},{"text":". ","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"How to request a Token","type":"text"}]},{"type":"paragraph","content":[{"text":"To request a token you use the authentication service. This service has a resource called token. On the token resource, you can use the POST method to get the authentication service to generate a token for you. When posting this request you have to provide some credentials.","type":"text"}]},{"type":"paragraph","content":[{"text":"There are three ways to authenticate and obtain a token: Client credentials grant, Password credentials grant and Trusted grant.","type":"text"}]},{"type":"paragraph","content":[{"text":"A client credentials flow is used when the application/client/app authenticates themselves and the actual user does not have to log in with their own credentials. This scenario also cover machine-to-machine communication, not involving a user directly.","type":"text"}]},{"type":"paragraph","content":[{"text":"Using the Password grant the users will authenticate themself with their own valid username and password. The Password “grant type” is used when you have communication between user and machine.","type":"text"}]},{"type":"paragraph","content":[{"text":"The Trusted flow is used when the application/client/app already have authenticated the user and wants to request a token for the logged in user without having to request for the users password again. We trust that the client has authenticated the user and knows who it is.","type":"text"}]},{"type":"paragraph","content":[{"text":"The parameters to the token services are handed over as form data of content type application/x-www-form-urlencoded.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Client credentials grant","type":"text"}]},{"type":"paragraph","content":[{"text":"To obtain an access (and refresh) token you must call the token service ","type":"text"},{"text":"POST /authentication/v2/token","type":"text","marks":[{"type":"strong"}]},{"text":". Required parameters are:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"grant_type=client_credentials","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"client_id=","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"client_secret=","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"scope (optional)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Parameters must be send using MIME type ","type":"text"},{"text":"application/","type":"text","marks":[{"type":"code"}]},{"text":"x-www-form-urlencoded","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"b1ea29e3-cbed-4aa7-8d57-359eeef1bd77"}},{"type":"code"}]},{"text":"or ","type":"text"},{"text":"application/json","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"codeBlock","content":[{"text":" https://beta-api.ambita.com/authentication/v2/token\n client_id=anClientId&client_secret=theSecret&grant_type=client_credentials\n ","type":"text"}]},{"type":"paragraph","content":[{"text":"If authentication is successful, a JSON will be returned:","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\n \"access_token\" : \"091ec7e2-40c5-43ea-9fb8-13e9f50b6db0\",\n \"token_type\" : \"Bearer\",\n \"expires_in\" : 3600,\n \"refresh_token\" : \"4db616c4-c72e-4022-96cc-f95816185531\",\n \"scope\":[]\n}\n ","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Password credentials grant","type":"text"}]},{"type":"paragraph","content":[{"text":"To obtain an access (and refresh) token you must call the token service ","type":"text"},{"text":"POST /authentication/v2/token","type":"text","marks":[{"type":"strong"}]},{"text":". Required parameters are:","type":"text"}]},{"type":"paragraph","content":[{"text":"For confidential clients the following parameters are required:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"grant_type=password","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"client_id=","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"client_secret=","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"username=","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"password=","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For non-confidential clients the following parameters are required:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"grant_type=password","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"client_id=","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"username=","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"password=","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Username and password are credentials registered in the Ambita Usercatalog. Parameters must be send using MIME type ","type":"text"},{"text":"application/x-www-form-urlencoded","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]},{"type":"codeBlock","content":[{"text":" https://beta-api.ambita.com/authentication/v2/token\n username=12000aUser&password=thePassword&grant_type=password&client_id=anClientId\n ","type":"text"}]},{"type":"paragraph","content":[{"text":"If authentication is successful, a JSON will be returned:","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\n \"access_token\" : \"091ec7e2-40c5-43ea-9fb8-13e9f50b6db0\",\n \"token_type\" : \"Bearer\",\n \"expires_in\" : 3600,\n \"refresh_token\" : \"4db616c4-c72e-4022-96cc-f95816185531\",\n \"scope\":[]\n}\n\n ","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Trusted grant","type":"text"}]},{"type":"paragraph","content":[{"text":"To obtain an access (and refresh) token you must call the token service ","type":"text"},{"text":"POST /authentication/v2/token","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Required parameters are:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"grant_type=trusted","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"client_id=","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"client_secret=","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"username=","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The user must be registered in the Ambita Usercatalog. Example below is using MIME type ","type":"text"},{"text":"application/x-www-form-urlencoded","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"codeBlock","content":[{"text":" https://beta-api.ambita.com/authentication/v2/token\n username=12000aUser&grant_type=trusted&client_id=aClientId&client_secret=aClientSecret\n ","type":"text"}]},{"type":"paragraph","content":[{"text":"If authentication is successful, a JSON will be returned:","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\n \"access_token\" : \"091ec7e2-40c5-43ea-9fb8-13e9f50b6db0\",\n \"token_type\" : \"Bearer\",\n \"expires_in\" : 3600,\n \"refresh_token\" : \"4db616c4-c72e-4022-96cc-f95816185531\",\n \"scope\":[]\n} ","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Refresh a token","type":"text"}]},{"type":"paragraph","content":[{"text":"When a token expires the client must choose between refreshing the token using the refresh_token or authenticating again as described above. Refreshing a token is pretty similar to authenticating. You don't need to send in client_id and client_secret for non-confidential clients. You post to the token service ","type":"text"},{"text":"POST /authentication/v2/token","type":"text","marks":[{"type":"strong"}]},{"text":" but uses grant_type=refresh_token. For confidential clients the following parameters are required:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"grant_type=refresh_token","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"client_id=","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"client_secret=","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"refresh_token=","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For non-confidential clients the following parameters are required:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"grant_type=refresh_token","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"refresh_token=","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Calling a service that demands an access token","type":"text"}]},{"type":"paragraph","content":[{"text":"When calling a service that requires an access token, the client must first obtain a token and then add the access token to the request header like this:","type":"text"}]},{"type":"codeBlock","content":[{"text":" Authorization: Bearer \n ","type":"text"}]},{"type":"paragraph"}],"version":1}

Browser not supported