Getting Started

You can use our test environment to develop and test your application.

To setup access and begin using our APIs, you will need to contact us for a username and password.

Test url: https://register.uat.kupe.fishserve.co.nz/

When you have completed testing, you will need to use an existing production username and password or set up new authorisations to access the live services.

Production url: https://fishserve.co.nz/

Below you will find information on;

  • Authentication: To authenticate each user. Used for FishServe APIs, and for registering an ERS logbook.
  • Registering ERS logbooks: To register a logbook device or request the expiry date of an existing registration.

Authentication

We offer three OAuth2 flows listed below, each has has specific application so please make sure you select the one that is appropriate for your application:

  1. The 'Authorisation Code Grant' flow (preferred)
    This flow is used in the situation where there is a third-party application and a third-party application server to communicate with Kupe.  The user of the third-party application is redirected to the standard Kupe login page where they enter their credentials before being redirected back to the third-party application.  This flow is more secure than the implicit flow because it includes a secure 'back channel' validation of a client secret.
  2. The 'Implicit' flow
    This flow is used in the situation where there is a third-party application, such as a JavaScript single page app, without a third-party application server, i.e. the third-party application communicates directly with Kupe.
  3. The 'Client Credentials' flow:
    This flow has been implemented to support business-to-business integration with Kupe.  There is no user interaction in this flow.  A third-party server 'logs in' to Kupe using a signed request to acquire an access token that can then be used to invoke protected Kupe APIs.

Note: Sharing of OAuth settings between our production and test environments is not permitted. Third parties will be issued a new client Id (relying party id) and secret for each environment. If you are using the Client Credentials (B2B) flow then a new public key will need to be supplied for each environment.

Response Status:

StatusDescription
5XX Internal Server Error Unknown Error. Please contact FishServe for help

The 'Authorisation Code Grant' Flow

Preparation

Before this flow can be used the following setup tasks are required:

Allocated to the third-party by FishServe:

  1. A 'client id' (aka relying party id), e.g. 'acme-inc'
  2. A unique client secret,
    (e.g. '759hyDGcrKjA8pBsLtTNmPEUYGZu2YDgPmRhvQlGExcDmjVW')

To be provided by the third party:

  1. The redirect URLs provided by third-parties are validated by FishServe to ensure the call is being redirected to the correct location. The third-party must nominate the redirect hostname for validation (e.g. 'acme-inc.co.nz').

Steps

  1. This flow starts when the third-party application needs to invoke a protected Kupe API.  First the application requests an authorisation code:
    e.g.     
    GET: https://auth.uat.kupe.fishserve.co.nz/oauth2/authorise?redirect_uri=https://acme-inc.co.nz/oauth2/afterkupelogin&client_id=acme-inc&state=10cdbad8-778f-4d11-861c-773ca1f1ba93&response_type=code&scope=openid
    The URL base: 
    UAT: https://auth.uat.kupe.fishserve.co.nz/oauth2/authorise
    Production: https://auth.kupe.fishserve.co.nz/oauth2/authorise
    The URL query string includes:
    redirect_url e.g. https://aceme-inc.co.nz/oauth2/afterkupelogin
    The URL Kupe will redirect the user to after successfully login.
    The hostname. e.g. 'acme-inc.co.nz', must match the hostname provided by the third-party as described in the Preparation section above.
    client_id e.g. 'acme-inc'
    A constant that identifies the third-party (allocated by FishServe).
    state e.g. C5BC3312-C5E7-4F60-8257-013F3789BFC2v
    A unique GUID created by the third-party.
    response_type Always 'code' for this flow.
    scope Always 'openid' for this flow
  2. The Kupe authorisation server redirects the call to the standard Kupe login page where the user enters their credentials.
  3. After successful login the authorisation server redirects the call to the third-party redirect provided in step 1. An authorisation code and state are included.
    e.g. https://acme-inc.co.nz/oauth2/afterkupelogin#code=eWjJCFPseM92dA==&state=10cdbad8-778f-4d11-861c-773ca1f1ba93

    The URL query string includes:
    The base URL e.g. https://acme-inc.co.nz/oauth2/afterkupelogin
    The redirect URL provided by the third-party in step 1
    code The authorisation code that can be exchanged for a bearer token in the next step.
    Authorization codes can only be used once and expire after a short period, 5 minutes.
    state The state value provided by the third-party in step 1.
  4. The third-party application server then calls the 'Get Token' API of the Kupe authentication server to exchange the authorisation code for an access token. This step is secure because it uses a 'back channel', i.e. server to server, and not the 'front channel' when using the browser in prior steps. e.g. 
    GET: https://auth.uat.kupe.fishserve.co.nz/oauth2/token?code=eWjJCFPseM92dA==&client_id=acme-inc&secret=759hyDGcrKjA8pBsLtTNmPEUYGZu2YDgPmRhvQlGExcDmjVW&grant_type=authorization_code
    The URL base:
    UAT: https://auth.uat.kupe.fishserve.co.nz/oauth2/token
    Production: https://auth.kupe.fishserve.co.nz/oauth2/token
    The URL query string includes:
    code The authorisation code returned in the previous step.
    client_id e.g. ‘acme-inc’. The relying party id allocated by FishServe, as described in the Preparation section above. 
    secret e.g. '759hyDGcrKjA8pBsLtUYGZu2YDgPmRhvQlGExcDmjVW'
    The client secret allocated by FishServe, as described in the Preparation section above. 
    grant_type Always 'authorization_code' for this flow.
  5. The authorisation server validates the request and returns the following on success: 
    {
  "AccessToken": "Pwk6KMXNuvNe8A==",
  "IdToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJS…8q31tVkJRNyKVaWJUq10HMgrfxUrk",
  "Error": null
}
  6. . The Id Token value can then be used to invoke protected Kupe API’s using the standard method of adding an 'Authorization' header with 'Bearer eyJ0eXAiOiJKV1QiLCJhbG…'.

The 'Implicit' Flow

Preparation

Before this flow can be used the following setup tasks are required:

Allocated to the third-party by FishServe:

  1. A 'client id' (aka relying party id), e.g. 'acme-inc'
  2. A unique client secret, 
    (e.g. '759hyDGcrKjA8pBsLtTNmPEUYGZu2YDgPmRhvQlGExcDmjVW')

Steps

  1. This flow starts when the third-party application needs to invoke a protected Kupe API and calls the following API to get an access token:
    e.g.     
    GET: https://auth.uat.kupe.fishserve.co.nz/oauth2/authorise?redirect_uri=https://localhost/oauth2/afterkupelogin&client_id=acme-inc&state=10cdbad8-778f-4d11-861c-773ca1f1ba93&response_type=token&scope=openid
    The URL base: 
    UAT: https://auth.uat.kupe.fishserve.co.nz/oauth2/authorise
    Production: https://auth.kupe.fishserve.co.nz/oauth2/authorise
    The URL query string includes:
    redirect_uri e.g. https://localhost/oauth2/afterkupelogin
    The URL Kupe will redirect the user to after successfully login.
    Is the location of a script in the third-party application that will extract the access token.
    (TBC - how should the hostname be restricted? Restrict to 'localhost'; or a nominated hostname?)
    client_id e.g. 'acme-inc'
    A constant that identifies the third-party (allocated by FishServe).
    state e.g. C5BC3312-C5E7-4F60-8257-013F3789BFC2v
    A unique GUID created by the third-party.
    response_type Always 'token' for this flow.
    scope Always 'openid' for this flow
  2. The Kupe authorisation server redirects the call to the standard Kupe login page where the user enters their credentials.
  3. After successful login the authorisation server redirects the call to the third-party redirect provided in step 1. An access token and state are included.
    e.g. https://localhost/oauth2/afterkupelogin#state=10cdbad8-778f-4d11-861c-773ca1f1ba93&access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjY2dix

    The URL includes:
    The base URL e.g. https://localhost/oauth2/afterkupelogin
    The redirect URL provided by the third-party in step 1.
    access_token The id/bearer token.
    state The state value provided by the third-party in step 1.
  4. The access_token value can then be used to invoke protected Kupe API’s using the standard method of adding an ‘Authorization’ header with ‘Bearer eyJ0eXAiOiJKV1QiLCJhbG…‘.

The 'Client Credentials' Flow

The Kupe authorisation server includes an implementation of the OAuth 2 ‘client credentials’ flow to enable third party servers to login and then invoke protected Kupe APIs.

The flow starts with the third-party invoking an API on the Kupe authorisation server with a request that includes a client secret and digital signature. If the request is valid then an access token is returned.

Preparation

Before using the client credentials flow the following setup tasks are required.

Note currently third-party details will need to be emailed to/from FishServe. In the future the details described below will be exchanged using a page on the FishServe website.

  1. To be performed by the third party:
    1. Generate a new RSA2048 key pair and give the public key to FishServe. This key pair will be used to generate and verify the signature in login requests. The third party uses the private key to generate the signature, and FishServe will use the public key to verify the signature.
    2. (optional?) The third party can provide the IP address of the third-party server that login requests will originate from. Login requests will be rejected if the IP address doesn’t match.
  2. To be performed by FishServe
    1. A new user in Kupe needs to be setup that will act as the identity of the third-party server. FishServe will configure the necessary clients and access roles for the user.
    2. FishServe allocates a ‘client id’ (aka ‘relying party id’) that will identify the third party (e.g. ‘acme-inc’).
    3. FishServe allocates a unique client secret to the third party (e.g. ‘759hyDGcrKjA8pBsLtTNmPEUYGZu2YDgPmRhvQlGExcDmjVW’).

Example: Generating a RSA2048 Key Pair

Below is an example of how to use OpenSSL to generate a new RSA2048 key pair.

  1. Install OpenSSL
  2. Create a new key pair and write them to an encrypted file private.pem:
    1. Command: openssl genrsa -des3 -out private.pem 2048
  3. Extract the public key from private.pem
    1. Command: openssl rsa -in private.pem -outform PEM -pubout -out public.pem
  4. Send the public.pem file to FishServe

Example public.pem:

-----BEGIN PUBLIC KEY-----

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAySnHUQxvYghXJfZ2dAnc
cniN108OHVJzVafCWXP3oNOymdDpAHGQATo64/L8UIrTxeEaI9n/SWe0pAI76O2m
FINmvcfLPPclE244m37kVPQRTvzi/mGPShEgmLhfnQZYjoQQs6sR920UJbkVlXOw
DR8h3SyFoxXNat9r9qEllP6IbOMdPcgWnOFPxkMxHml6EMW1e8kyp9C1tBPW95gj
27kRUdgV7FWdBIjWwL+YiHoXQLIRV1IlYq1Asl+c87k5FbgwXUXqT2/eAtGhjlOP
86B/j9Oe9hVjH4M6z+eKP1RMFuvnwfek6m3jM5S7sl0TQc3dSjQyHW/C7754yo2Z
LwIDAQAB

-----END PUBLIC KEY-----

Steps

    1. To start the flow the third party first prepares a signed request:
      1. The request body (json) e.g. 
        {
  grant_type: "client_credentials",
  client_id: "acme-inc",
  client_secret: "759hyDGcrKjA8pBsLtTNmPEUYGZu2YDgPmRhvQlGExcDmjVW",
  scope: "openid",
  requested_datetime: "2018-10-18T13:20:43+13:00"
}
        1. grant_type: always 'client_credentials'
        2. client_id: the allocated third-party client id
        3. client_secret: the allocated third-party secret
        4. scope: always 'openid'
        5. requested_datetime: the date/time the request was prepared. The request will be rejected if requested_datetime is not within 10 minutes of the current date/time.
      2. Next a digital signature for the request body is generated:
        1. Remove all formatting characters from the request body (carriage returns, linefeeds, tabs etc) then convert the request body to use the UTF8 character set,
        2. The SHA256 hash value of the request body is calculated,
        3. The hash value is signed using the private key
        4. The signature is base64 encoded
        5. The encoded signature is added to the HTTP headers collection of the request (key='Signature')
      3. The request is then posted to the Kupe authorisation server:
        URLs 
        UAT
POST: https://auth.uat.kupe.fishserve.co.nz/oauth2/b2b/token
Production (once released)
POST: https://auth.kupe.fishserve.co.nz/oauth2/b2b/token
    2. If the request is successful, then the following is returned:
      {
  "token_type": "Bearer",
  "access_token": "eyJ0eXAiOiJKV1Qi...FpZAMkdH4Q-Rcwb6EKqG9OlOc",
  "expires_in": 1440,
  "error": ""
}
    3. The access token can then be used to invoke protected Kupe API’s using the standard method of adding an ‘Authorization’ header with ‘Bearer eyJ0eXAiOiJKV1Q…‘.

Beware

Three consecutive failed login attempts where the client secret or signature is invalid will cause B2B login attempts to be blocked for 30 minutes. This is consistent with the blocking logic when using the website login page (this restriction is being reviewed).

Back to top

Logbook Registration

All users must register their logbooks to be able to submit ERS event APIs to FishServe.

This API is also used to provide FishServe with a new Public key if one is needing to be renewed or otherwise replaced.

All 3rd party software must use digital signature algorithms to meet the authentication requirements for submitting ERS event reports. The algorithm chosen is ECDSA (ANSI X9.62) NIST P-256 elliptic curve known as prime256v1 or secp256r1.

If you need help testing your logbook digital signatures, visit our digital signature test information here.

When a logbook is submitted with a new Public Key the previous public key will enter a ‘grace period’ which will expire the following day at midnight.

The new public key will have an expiry date in 6 months’ time.

The Create API request requires;

          • Software Vendor
          • Device Name
          • Software Installation Id
          • Public Key

The response provides;

          • User ID
          • Expiry Date Time

Alternatively, the GET API can be used to return the expiry date of an existing registration.

Registering ERS Logbooks Technical Information

All users must register their logbooks to be able to submit ERS event APIs to FishServe.

The authorisation for this API is the same as other FishServe APIs - see the Authentication information above. 

Request

Request Url
POST https://ers.uat.kupe.fishserve.co.nz/api/security/log-book-registration
Request Header
Content-Type: application/json
Authorization: Bearer YOUR_USER_Token
Request Body Parameters
ParameterRequiredData typeDescription
Software Vendor Mandatory String The name of the software vendor.
Device Name Mandatory String The name of your device.
Software Installation Id Mandatory String

GUID format.

Unique Identifier of the device.
Public Key Mandatory String

The public key that is generated from the digital signature algorithm on your logbook.

Must be unique for each combination of software installation id and user.

Note: The logbook will have to store the private key that matches the public key.
Request Body
{
  "SoftwareVendor": "{SoftwareVendor}",
  "DeviceName": "{DeviceName}",
  "SoftwareInstallationId" : "{SoftwareInstallationId}",
  "PublicKey": "{PublicKey}"
}

Example:

{
  "SoftwareVendor": "LogBook Co 123",
  "DeviceName": "Vessel Computer",
  "SoftwareInstallationId" : "74be4716-cd8f-4264-83e4-5b1249082503",
  "PublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEX98JTRSsAYUnQ3HfwnlEQGNLb8sCczFhlYSukPRMpmtgDSQA4PphkDaMTYRrEwW/94moJmY8kakp0PwamSUQjg=="
}

Response

Response Parameters
ParameterData typeDescription
User Id String

The user access token.

To be used as Completer User Id on the payload.
Expiry Date Time String

Date Time in 24hr format.

The registration will expire every 6 months.

A user can have multiple registrations for different devices, but only one registration per device.
Errors Array

List of errors, if any. See Error Parameters below.

Errors Parameters:

ParameterData TypeDescription
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.
Response Body
{
    "userId": "{userId}",
    "expiryDateTime": "{expiryDateTime}",
    "errors": []
}

Example:

{
    "userId": 25,
    "expiryDateTime": "2018-03-01T00:00:00+13:00",
    "errors": []
}

Back to top

Get

Use this API to retrieve the expiry date of an existing registration.

Request Url
GET https://ers.uat.kupe.fishserve.co.nz/api/security/log-book-expiry?softwareInstallationId={softwareInstallationId}&completerUserId={completerUserId}
Example
GET https://ers.uat.kupe.fishserve.co.nz/api/security/log-book-expiry?softwareInstallationId=74be4716-cd8f-4264-83e4-5b9249083802&completerUserId=8965
Request Header
Content-Type: application/json
Signature: signature generated from the digital signature algorithm using the request URL and private key.

Response Status
StatusDescription
200 OK Status for a successful request. 
500 Internal Server Error  Status when something is wrong with the request. 
Response Parameters
ParameterData type
Expiry Date Time 

Logbook registration expiry date. 
Response Body
{
    "{expiryDateTime}"
}
Example:
{
    "expiryDate" : "2018-03-01T00:00:00+13:00"
}

Back to top