Jump to

• Request
• Response
• Examples

Get an access token

post

/rest/oauthTokenService/v2/token

This operation authenticates the calling application and retrieves the access token.

Request

Supported Media Types

• application/x-www-form-urlencoded

Form Parameters

• assertion: string

  The JWT assertion token. This field contains the assertion token only when the grant_type is 'urn:ietf:params:oauth:grant-type:jwt-bearer'.

  The JWT assertion token structure is as follows:

  • Header: The header should contain 'alg' field set to 'RS256'. For example, { "alg" : "RS256" }.
  • Payload: The payload should contain the following fields:
    • "iss" - the name of the person who issued the assertion token. This field is only for information/logging purposes and is not used for validation.
    • "aud" - the audience for the assertion token. It is a string composed of three parts delimited by colon. The first part of the string is always 'ofsc', the second part is the Oracle Field Service environment name, and the third part is the Application ID. For example, "ofsc:bestcustomer:best_mobile_app".
    • "sub" - the subject of the assertion token. It can either be equal to "aud" (if we perform the call as application, not as a Oracle Field Service user), or it can be equal to the "login" field of an Oracle Field Service user that you want to authorize to call the REST APIs.
    • "iat" - the UNIX timestamp when the assertion was issued.
    • "exp" - the UNIX timestamp when the assertion expires. The "exp" time should be kept short, for example, a minute or a few minutes.

    The following is an example JWT assertion token that you can copy-paste to https://jwt.io to see the fields:

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJwaGlsbGlwIiwiYXVkIjoib2ZzYzp5YW1hdG86NTM0ZjgyYThkMWFjMmE0N2RhOWNmZTk1YTRjOGJmOWI4N2I2NjU1MyIsImlzcyI6Im15IG1vbW15IiwiaWF0IjoxNDg1NDY5MzY0LCJleHAiOjE0ODU0Njk0OTR9.Y8fAyCvJ1EqGip0jgOb8VjwjPq3WDZuTRsFrZSfNSSH-8QXTyj11adQPDH8OZKrpTyPMtxHGZscBniimCpA7w-0_9TDCNf4v1mHvWgNZDI-Q8qe7wr66rrH1wGpBDX6QijGw2GU_642aw6hXo2YVtViUz9NJ0W-sLj1y7yamwJPiJNGx_diiQJxMJ4pPzqs6H1KxkucmSlbKMjscausF8NVqpB_wupcuSxlvo5-mCDsbfZrDPMgnvi1SqoaHOrzTiPSFp96dowXnVnlsHcypASczmQvz30MIuQvHLGJq_HRTXcgzZ5ofY0At823c1dPY0Jfri172TadT5jc10g4QHg

• grant_type(required): string
  The type of the authentication. The allowed values are:

  • 'client_credentials' - HTTP Basic authentication is used to authenticate the calling application. The 'client_id' and 'client_secret' are used as the credentials.
  • 'urn:ietf:params:oauth:grant-type:jwt-bearer' - JWT Assertion token is used to authenticate the calling application.

  Allowed Values: [ "client_credentials", "urn:ietf:params:oauth:grant-type:jwt-bearer" ]
• ofsc_dynamic_scope: string
  If the value of this parameter adds an additional claim to the access token returned in response with the same name and value. The 'ofsc_dynamic_scope' parameter and the claim have the URL format with optional query parameters. The claim applies the following restrictions to the requests:

  • endpoint: Oracle Field Service REST API rejects the token with HTTP 401 status code, if it is used to call a different endpoint other than the one specified in 'ofsc_dynamic_scope' claim.
  • query fields: Oracle Field Service REST API rejects the request with HTTP 401 status code, if the request URL does not contain all the query parameters specified in the 'ofsc_dynamic_scope' claim.
  • query values: Oracle Field Service REST API rejects the request with HTTP 401 status code, if all the query parameter values specified in the request URL do not match the query parameter values of the 'ofsc_dynamic_scope' claim.

  Multiple URLs can be specified in this parameter and claim. The URLs must be separated by a single space.

  In the following cURL command example, the value of the 'ofsc_dynamic_scope' parameter is set to "https://<environment_name>.fs.ocs.oraclecloud.com/rest/ofscCore/v1/whereIsMyTech?activityId=12345" (value is URL-encoded in the command) curl -u 'client_id@environment_name:client_secret' -X POST --url 'https://<environment_name>.fs.ocs.oraclecloud.com/rest/oauthTokenService/v2/token' -d 'grant_type=client_credentials' -d 'ofsc_dynamic_scope=https%3A%2F%2F<environment_name>.fs.ocs.oraclecloud.com%2Frest%2FofscCore%2Fv1%2FwhereIsMyTech%3FactivityId%3D12345'

Back to Top

Response

Supported Media Types

• application/json

200 Response

This section describes the 200 status response for this operation.

Body ()

Root Schema : schema

Type: object

Show Source

• access_token: string
  Title: Token

  The access token.
• expires_in: integer
  Title: Expires In

  The validity of the access token in seconds.
• token_type: string
  Title: Token Type

  The type of the assertion token.

{
    "type":"object",
    "properties":{
        "access_token":{
            "type":"string",
            "title":"Token",
            "description":"The access token."
        },
        "token_type":{
            "type":"string",
            "title":"Token Type",
            "description":"The type of the assertion token."
        },
        "expires_in":{
            "type":"integer",
            "title":"Expires In",
            "description":"The validity of the access token in seconds."
        }
    }
}

Default Response

This section describes the default error response for this operation.

Body ()

Root Schema : Error

Type: object

Show Source

• detail: string
  The detailed description of this error.
• status: string
  The HTTP status code of this error.
• title(required): string
  The brief description of this error.
• type(required): string
  The URL of the web page containing more details about this error.

{
    "properties":{
        "type":{
            "type":"string",
            "description":"The URL of the web page containing more details about this error."
        },
        "title":{
            "type":"string",
            "description":"The brief description of this error."
        },
        "status":{
            "type":"string",
            "description":"The HTTP status code of this error."
        },
        "detail":{
            "type":"string",
            "description":"The detailed description of this error."
        }
    },
    "required":[
        "type",
        "title"
    ]
}

Back to Top

Examples

The following example shows how to fetch an access token by submitting a POST request on the REST resource:

cURL command Example

curl -X POST -u '<CLIENT-ID>@<INSTANCE-NAME>:<CLIENT-SECRET>' \ 
-d 'grant_type=client_credentials' \
'https://<instance_name>.fs.ocs.oraclecloud.com/rest/oauthTokenService/v2/token'

Response Body Example

The following shows an example of the response body in JSON format.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
 
{
    "access_token": "eyJ0eXAiOiJ...SKIP...Atbt71aUa_Qmy98w",
    "token_type": "bearer",
    "expires_in": 3600
}

Back to Top