Authentication


Table of contents

    To authenticate an application, it must be registered with the MYP API service. To register an application, follow the steps outlined in this article.

    Register application

    To register an application with the MYP API, you must be an MYP Subscriber with relevant API permissions. Your MYP Champion can assign these permissions where required.

    To register an application:

    • Log in to MYP
    • Navigate to ARM Pro > Administration > API applications via the side navigation menu
    • Select ‘Add API application’
    • Enter the application details:
      • Application name: the name of your application
      • Organisation URL: the URL of your organisation or application
    • Select ‘Generate keys’ to generate the client_id and client_secret keys
    Image 1 for registering API application

    After the application has been successfully registered, you will receive a client_id and a client_secret, which are required to obtain an access token.

    NB: The client secret is like a password for your application. Once generated, client secrets cannot be retrieved, so save it in a secure location. If you lose the client secret, you will have to re-register your application.

    • If you would like to redirect users to more than one URL after they log in, select ‘Add’ (the ‘+’ icon next to ‘OAuth redirect URL’) to add more redirect URLs
    • Select ‘Save’ to finish registering the application
    Image 2 for registering API application

    Get access token

    When an application needs to use the MYP API to access business data, it needs to have an access token for authentication. The access token can be obtained from our Authentication Endpoint by using the client id and client secret which were generated when the application was registered.

    To obtain the access token, a POST API request needs to be sent with the following headers and body values:

    POST: https://identity.mypcorp.com/connect/token

    Headers
    Key Value Description
    Content-Type application/x-www-form-urlencoded The request format.
    Body
    Key Value Description
    client_id {your_client_id} The id for your application which was generated on registration.
    client_secret {your_api_secret} The secret for your application which was generated on registration.
    grant_type client_credentials Method by which application gets an access token.
    scope {your_list_of_scopes} List of scopes, separated by space, for which the token is requesting access for.

    NB: omitting to provide scope returns all available scopes.

    Here is an example JSON response:

    {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9.eyJuYmYiOjE2MDIxMTc4NDIsImV4cCI6MTYwMjEyMTQ0MiwiaXNzIjoiaHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMSIsImNsaWVudF9pZCI6ImNsaWVudCIsImp0aSI6IjRENjBEMUZDQTc2RTRCRDdFNzlGRjFDRDg0QTlGMTU0IiwiaWF0IjoxNjAyMTE3ODQyLCJzY29wZsSI6WyJjbGllbnQucmVhZCIsImNvbnRhY3QucmVhZCIsImNvbnRhY3Qud3JpdGUiLCJzdGFmZi5yZWFkIl19.i-0ovy-rF0pkAgyBEq6_IkiH0VqgQkSPGsS-aSrCT1AYzb3Jrw7BD6q07fpx_Gj_2K4Xm2pjb7F5mYT2UaEWdfwUV2doAsCeBdQUj-rl6euroIrMlgQyPPG-TxjeSI9Vos_VGu9DfUQfPrVg1JA94uufxwykIoasFnfj5CqqXiLkZPIr1cG6ahQM9_TMBAd9BZfFlARlcP4w-GsJpJ8iwor-wpGKvKM5lNqudL7xKCaAHxRVQL0LWLsCXJIeyvrD7wt_UYli-q7oAmoRX0O_Si1zbuxXNpl3uJ09k02IcEg96LYCgSQwdckSTHEpiT97raHm1M39u5tq8BMTkQ0dD6Q",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "client.read contact.read contact.write staff.read"
}
    • “access_token”: a JSON web token (JWT) that should be passed as a parameter when calling the MYP API
    • “expires_in”: how long the token is active for (in seconds), after it has been created
    • “token_type”: the type of JWT
    • “scope”: the level of access the token has

    NB: After the token has expired, you will need to obtain a new access token to call MYP API.

    Scopes

    Below are the scope options that can be requested from MYP Authorisation server if the Client has been given permission to access them:

    Scope Description
    client.read Read access for Client, Invoice, Claim and Provider Invoice endpoints
    client.write Write access for Client endpoint
    contact.read Read access for Contact, Invoice, Claim and Provider Invoice endpoints
    contact.write Write access for Contact endpoint
    staff.read Read access for Staff, Invoice, Claim and Provider Invoice endpoints
    staff.write Write access for Staff endpoint
    team.read Read access for Team endpoint
    document.read Read access for Document, Document Category and Provider Invoice endpoints
    document.read Write access for Document and Document Category endpoints
    opportunity.read Read access for Opportunity, OpportunityTemplate, OpportunityType, OpportunityStage and OpportunityOutcomeReason endpoints
    opportunity.write Write access for Opportunity, OpportunityTemplate, OpportunityType, OpportunityStage and OpportunityOutcomeReason endpoints
    timesheet.read Read access for Timesheet endpoint
    genius.invoice.read Read access for Pricebook, CostCentre and Invoice endpoints
    genius.invoice.write Write access for Invoice endpoint
    genius.claim.read Read access for Pricebook, CostCentre, Provider Invoice and Claim endpoints
    genius.claim.write Write access for Claim and Provider Invoice endpoints
    genius.engagement.read Read access for ClientEngagement endpoint.

    Previous article Next article