In order to be able to use the BCDE web services API you will need a web services API key.

A web services key will need to be issued out to you by Bentley. Issuing the key includes registering your application against a specific BCDE server.

When your application is registered, certain information needs to be included in the registration, which affects how your application can behave. In order to be able to register your application correctly, we will need to know this information about your application. We ask for that information at the point that you apply for your web services key.

Initially we will give you access to a beta server, which is a copy of a live server.

In particular:

1. You need to think about which users your application will act as.
   There are two options, you must specify one.
   
   
   • OPTION 1
     Do you want your application to carry out all of its actions as one user account? The user account will not be used by any human for manual activities. This is sometimes called a service user account.
     If this is how you would like your application to behave you will need to:
     • Create a user account on the BCDE server that will be used as a service user account
       • This user should have the access rights (company access, membership, admin rights etc.) that will allow the application to carry out the actions that it needs to do.
       • This user should have an associated email address that is not tied to an individual - ideally it should be a shared inbox. That way if someone leaves the business, you will retain access to the email address. The email address should be monitored in case BCDE support need to contact you regarding the application.
     • Request an application that uses JWT authentication with a system user account
       • As part of your application you will also need to provide the BCDE username (the user must already exist when you make your application)
       • If the application's user will require admin rights to carry out its activities, make sure this is indicated in your application
       • You will also need to generate a public JWT key. Instructions for doing this are here: https://gitlab.com/groupbc/webservice-examples/-/blob/master/guides/authenticate_jwt.md 
         
         
       • For added security, we require you to specify an IP range from which your application will be making requests to the BC API. It is OK for this to be a different IP address or range from your test/development set up to your live set up.
         
         
   • OPTION 2
     Do you want your application to be able to carry out actions on behalf of real users on the system, who will also be logging in through the front end to do manual actions?
     If this is how you would like your application to behave you will need to:
     • Request an application that uses OAuth authentication
       
       • Please note: if you choose OAuth authentication then there is an additional manual step that is needed during authentication. The manual user themselves needs to authorise the application to work on their behalf before the application will be able to carry out any actions as that person. Your application will need to be able to handle this part of the process.
         
         
2. For an application running on a live server, we require you to specify which endpoints your application will be using. Any endpoints that are not specified will be blocked for use by your application. This is following the principle of least access. We appreciate that during your development phase you may not be aware of which endpoints you require so we do not require that you specify a list of endpoints for a test/development application.

If any of the information above is not supplied, we cannot complete the registration of your application on the BC server.

To request a key please follow these steps.

1. Ensure you have answers to the above points.
   
   
2. Contact Bentley Support and request the setup of a web services API key:
   1. Please specify whether this is an application in development or whether it is a live deployment of an already developed application (the process and requirements are slightly different)
   2. Please specify the URL of the live server your application will be connected with. From this URL the support team will be able to identify the appropriate Beta server URL, and will confirm this back to you.
      
      
3. They will provide you with a form to complete.
   1. Please ensure all the information is supplied, including the information requested in the points above.
      
      
   2. Please make sure that a server owner is copied in on your request - if you do not know who the server owner is, check with Bentley Support. This step is to ensure that the server is aware and approve the use of the APIs on the server.
      
      
4. The form will go through a Bentley approvals process. 
   
   
5. Once approved, the request will go to our technical team.
   1. If necessary they will perform a reset of the beta server so that your service user account is available to use.
   2. They will complete the registration of your app on the beta server and will provide the key details to you through the Bentley support team. These keys will initially only allow API access to the beta server.
      
      
6. When you have completed development of your application, you should apply to go live.
   1. Contact the Bentley Support team and notify them that you would like to make your Web Services Application available on the live server.
      1. Please ensure that any service user accounts already exist on the live system.
   2. They will ask for additional information about your application:
      1. If using a JWT system account you will need to supply the IP Address or IP range that your application will be making requests from. Requests made from other IP addresses other than the ones you supply will be blocked.
      2. If using a JWT system account please supply a new public key to be used on live.
      3. Please supply a list of the endpoints that your application is using. If your Application makes a request through an endpoint that is not listed, the request will be blocked.
         
         
7. The request will go to our technical team.
   1. They will complete the registration of your app on the live server and will provide the key details to you through the Bentley support team. These keys will only allow API access to the live server. (We do not permit the same keys to be used on the beta and live servers.)